openapi: 3.0.3 info: title: Efí (formerly Gerencianet) Payments Authorization Pix Charges API description: "Representative subset of Efí's public REST APIs for the Brazilian financial system. Efí (ex-Gerencianet) is a Brazilian payment institution and digital bank. This document groups operations across several distinct API hosts, each with its own base URL and authentication requirements:\n\n- Pix API - base https://pix.api.efipay.com.br (sandbox\n https://pix-h.api.efipay.com.br). OAuth2 client-credentials (token at\n POST /oauth/token) PLUS a mandatory mutual TLS (mTLS) client certificate\n (.p12/.pem) on every request, as required by the Brazilian Central Bank.\n Paths under /v2/*.\n\n\n- Cobranças (Charges) API - base https://cobrancas.api.efipay.com.br (sandbox\n https://cobrancas-h.api.efipay.com.br). OAuth2 client-credentials over HTTP\n Basic (token at POST /v1/authorize). No mTLS certificate required. Paths\n under /v1/charge, /v1/charges, /v1/carnet.\n\n\n- Pix via Open Finance API - base https://openfinance.api.efipay.com.br\n (sandbox https://openfinance-h.api.efipay.com.br). OAuth2 client-credentials\n (token at POST /v1/oauth/token) PLUS a mandatory mTLS certificate.\n\n\nBecause OpenAPI 3.0 has a single security-scheme model, the mTLS requirement for the Pix and Open Finance hosts is described here in prose and cannot be fully expressed as a securityScheme; treat the mTLS client certificate as mandatory on those hosts in addition to the OAuth2 bearer token. Endpoints marked \"modeled\" in the repository review follow the Brazilian Central Bank Pix API v2 standard that Efí implements; the create/query charge, webhook, charge, and carnê operations were confirmed directly against Efí's public documentation." version: '1.0' contact: name: Efí Developers url: https://dev.efipay.com.br servers: - url: https://pix.api.efipay.com.br description: Pix API - production (mTLS certificate required) - url: https://pix-h.api.efipay.com.br description: Pix API - sandbox / homologação (mTLS certificate required) - url: https://cobrancas.api.efipay.com.br description: Cobranças (Charges) API - production - url: https://openfinance.api.efipay.com.br description: Pix via Open Finance API - production (mTLS certificate required) security: - oAuth2ClientCredentials: [] tags: - name: Pix Charges description: Immediate (cob) and dated (cobv) Pix charges and payload locations. Host pix.api.efipay.com.br, mTLS required. paths: /v2/cob: post: operationId: createImmediateCharge tags: - Pix Charges summary: Create an immediate Pix charge (server-generated txid) description: Creates an immediate Pix charge (cob) without providing a txid; Efí generates it. Scope cob.write. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CobRequest' responses: '201': description: The created immediate charge. content: application/json: schema: $ref: '#/components/schemas/Cob' '401': $ref: '#/components/responses/Unauthorized' get: operationId: listImmediateCharges tags: - Pix Charges summary: List immediate Pix charges description: Lists immediate charges over a date range. Query parameters inicio and fim are mandatory. Scope cob.read. parameters: - name: inicio in: query required: true description: Start of the filter interval (RFC 3339 timestamp). schema: type: string format: date-time - name: fim in: query required: true description: End of the filter interval (RFC 3339 timestamp). schema: type: string format: date-time responses: '200': description: A paginated list of immediate charges. content: application/json: schema: $ref: '#/components/schemas/CobList' '401': $ref: '#/components/responses/Unauthorized' /v2/cob/{txid}: parameters: - $ref: '#/components/parameters/Txid' put: operationId: createImmediateChargeWithTxid tags: - Pix Charges summary: Create an immediate Pix charge with a given txid description: Creates an immediate Pix charge (cob) using a caller-supplied txid. Scope cob.write. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CobRequest' responses: '201': description: The created immediate charge. content: application/json: schema: $ref: '#/components/schemas/Cob' '401': $ref: '#/components/responses/Unauthorized' patch: operationId: reviseImmediateCharge tags: - Pix Charges summary: Revise an immediate Pix charge description: Revises fields of an existing immediate charge, creating a new revision. Scope cob.write. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CobRequest' responses: '200': description: The revised immediate charge. content: application/json: schema: $ref: '#/components/schemas/Cob' '401': $ref: '#/components/responses/Unauthorized' get: operationId: getImmediateCharge tags: - Pix Charges summary: Retrieve an immediate Pix charge description: Retrieves an immediate charge by txid; supports the optional revisao query parameter. Scope cob.read. responses: '200': description: The requested immediate charge. content: application/json: schema: $ref: '#/components/schemas/Cob' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /v2/cobv/{txid}: parameters: - $ref: '#/components/parameters/Txid' put: operationId: createDatedCharge tags: - Pix Charges summary: Create a dated Pix charge (cobv) description: Creates a Pix charge with a due date (cobv). Modeled on the Brazilian Central Bank Pix API v2 standard that Efí implements. Scope cobv.write. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CobvRequest' responses: '201': description: The created dated charge. content: application/json: schema: $ref: '#/components/schemas/Cobv' '401': $ref: '#/components/responses/Unauthorized' get: operationId: getDatedCharge tags: - Pix Charges summary: Retrieve a dated Pix charge (cobv) description: Retrieves a dated charge by txid. Modeled on the BACEN Pix API v2 standard. Scope cobv.read. responses: '200': description: The requested dated charge. content: application/json: schema: $ref: '#/components/schemas/Cobv' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /v2/loc: post: operationId: createLocation tags: - Pix Charges summary: Create a payload location description: Creates a payload location (loc) used to generate the dynamic QR Code / Pix Copia e Cola payload. Modeled on the BACEN Pix API v2 standard. Scope loc.write. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LocationRequest' responses: '201': description: The created payload location. content: application/json: schema: $ref: '#/components/schemas/Location' '401': $ref: '#/components/responses/Unauthorized' components: schemas: CobvRequest: type: object properties: calendario: type: object properties: dataDeVencimento: type: string format: date validadeAposVencimento: type: integer devedor: $ref: '#/components/schemas/Devedor' valor: $ref: '#/components/schemas/Valor' chave: type: string LocationRequest: type: object properties: tipoCob: type: string enum: - cob - cobv CobList: type: object properties: parametros: type: object additionalProperties: true cobs: type: array items: $ref: '#/components/schemas/Cob' Devedor: type: object properties: cpf: type: string cnpj: type: string nome: type: string Valor: type: object properties: original: type: string example: '123.45' CobRequest: type: object properties: calendario: type: object properties: expiracao: type: integer example: 3600 devedor: $ref: '#/components/schemas/Devedor' valor: $ref: '#/components/schemas/Valor' chave: type: string description: Pix key (chave) that receives the payment. solicitacaoPagador: type: string Cobv: allOf: - $ref: '#/components/schemas/CobvRequest' - type: object properties: txid: type: string status: type: string location: type: string pixCopiaECola: type: string Location: allOf: - $ref: '#/components/schemas/LocationRequest' - type: object properties: id: type: integer location: type: string criacao: type: string format: date-time Error: type: object properties: nome: type: string mensagem: type: string error: type: string error_description: type: string Cob: allOf: - $ref: '#/components/schemas/CobRequest' - type: object properties: txid: type: string revisao: type: integer status: type: string enum: - ATIVA - CONCLUIDA - REMOVIDA_PELO_USUARIO_RECEBEDOR - REMOVIDA_PELO_PSP location: type: string pixCopiaECola: type: string responses: Unauthorized: description: Missing or invalid OAuth2 token, or (on Pix / Open Finance) a missing or invalid mTLS certificate. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' parameters: Txid: name: txid in: path required: true description: Transaction identifier (26-35 alphanumeric characters). schema: type: string securitySchemes: oAuth2ClientCredentials: type: oauth2 description: 'OAuth2 client-credentials. Obtain a bearer token from the host''s token endpoint using HTTP Basic auth (Client_Id / Client_Secret), then send it as Authorization: Bearer. On the Pix and Open Finance hosts a mutual TLS (mTLS) client certificate (.p12/.pem) is additionally mandatory on every request, including the token request, per Brazilian Central Bank rules.' flows: clientCredentials: tokenUrl: https://pix.api.efipay.com.br/oauth/token scopes: cob.write: Create and revise immediate Pix charges. cob.read: Read immediate Pix charges. cobv.write: Create and revise dated Pix charges. cobv.read: Read dated Pix charges. pix.write: Request Pix refunds. pix.read: Read received Pix and refunds. pix.send: Send Pix (Cash-Out). loc.write: Create payload locations. webhook.write: Configure and delete webhooks. webhook.read: Read webhooks. gn.opb.participants.read: Read Open Finance participants. gn.opb.payment.pix.send: Initiate Pix via Open Finance. gn.opb.payment.pix.read: Read Open Finance payments.