Create and manage Pix charges - immediate charges (cob) and dated charges with due date (cobv) - plus payload locations (loc) that generate the dynamic QR Code and Pix Copia e Cola payload. Requires OAuth2 client-credentials and a mandatory mTLS certificate.
openapi: 3.0.3
info:
title: Efí (formerly Gerencianet) Payments 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:
- Pix API - base https://pix.api.efipay.com.br (sandbox
https://pix-h.api.efipay.com.br). OAuth2 client-credentials (token at
POST /oauth/token) PLUS a mandatory mutual TLS (mTLS) client certificate
(.p12/.pem) on every request, as required by the Brazilian Central Bank.
Paths under /v2/*.
- Cobranças (Charges) API - base https://cobrancas.api.efipay.com.br (sandbox
https://cobrancas-h.api.efipay.com.br). OAuth2 client-credentials over HTTP
Basic (token at POST /v1/authorize). No mTLS certificate required. Paths
under /v1/charge, /v1/charges, /v1/carnet.
- Pix via Open Finance API - base https://openfinance.api.efipay.com.br
(sandbox https://openfinance-h.api.efipay.com.br). OAuth2 client-credentials
(token at POST /v1/oauth/token) PLUS a mandatory mTLS certificate.
Because 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: Authorization
description: OAuth2 client-credentials token endpoints (per host).
- name: Pix Charges
description: Immediate (cob) and dated (cobv) Pix charges and payload locations. Host pix.api.efipay.com.br, mTLS required.
- name: Pix Payments
description: Received Pix, sent Pix, and refunds. Host pix.api.efipay.com.br, mTLS required.
- name: Pix Webhooks
description: Webhook registration for received-Pix notifications. Host pix.api.efipay.com.br, mTLS required.
- name: Cobranças
description: Boleto / card / Pix charges. Host cobrancas.api.efipay.com.br, no mTLS.
- name: Carnê
description: Installment booklets. Host cobrancas.api.efipay.com.br, no mTLS.
- name: Open Finance
description: Pix payment initiation via Open Finance. Host openfinance.api.efipay.com.br, mTLS required.
paths:
/oauth/token:
post:
operationId: pixAuthorize
tags:
- Authorization
summary: Obtain a Pix API access token
description: >-
OAuth2 client-credentials token endpoint for the Pix API host. Send HTTP
Basic auth with Client_Id and Client_Secret. This request also requires
the mTLS client certificate.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRequest'
responses:
'200':
description: Access token issued.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/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'
/v2/pix:
get:
operationId: listReceivedPix
tags:
- Pix Payments
summary: List received Pix
description: >-
Lists received Pix over a date range (Cash-In). Query parameters inicio
and fim are mandatory. Modeled on the BACEN Pix API v2 standard. Scope
pix.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 received Pix.
content:
application/json:
schema:
$ref: '#/components/schemas/PixList'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/pix/{e2eid}:
parameters:
- name: e2eid
in: path
required: true
description: The end-to-end identifier of the Pix transaction.
schema:
type: string
get:
operationId: getReceivedPix
tags:
- Pix Payments
summary: Retrieve a received Pix
description: Retrieves a single received Pix by its end-to-end id. Modeled on the BACEN Pix API v2 standard. Scope pix.read.
responses:
'200':
description: The requested received Pix.
content:
application/json:
schema:
$ref: '#/components/schemas/Pix'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v2/pix/{e2eid}/devolucao/{id}:
parameters:
- name: e2eid
in: path
required: true
description: The end-to-end identifier of the Pix transaction.
schema:
type: string
- name: id
in: path
required: true
description: Client-defined refund identifier.
schema:
type: string
put:
operationId: requestRefund
tags:
- Pix Payments
summary: Request a Pix refund (devolução)
description: >-
Requests a refund (devolução) for a received Pix, identified by the
end-to-end id and a client refund id. Modeled on the BACEN Pix API v2
standard. Scope pix.write.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RefundRequest'
responses:
'201':
description: The created refund.
content:
application/json:
schema:
$ref: '#/components/schemas/Refund'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: getRefund
tags:
- Pix Payments
summary: Retrieve a Pix refund
description: Retrieves a refund by end-to-end id and refund id. Modeled on the BACEN Pix API v2 standard. Scope pix.read.
responses:
'200':
description: The requested refund.
content:
application/json:
schema:
$ref: '#/components/schemas/Refund'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v2/webhook/{chave}:
parameters:
- name: chave
in: path
required: true
description: The Pix key (chave) the webhook is associated with.
schema:
type: string
put:
operationId: configureWebhook
tags:
- Pix Webhooks
summary: Configure a Pix webhook
description: Registers the callback URL that Efí will POST received-Pix notifications to for a given Pix key. Scope webhook.write.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookRequest'
responses:
'200':
description: Webhook configured.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: getWebhook
tags:
- Pix Webhooks
summary: Retrieve a Pix webhook
description: Retrieves the webhook configured for a given Pix key. Scope webhook.read.
responses:
'200':
description: The configured webhook.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteWebhook
tags:
- Pix Webhooks
summary: Cancel a Pix webhook
description: Cancels the webhook associated with a given Pix key. Scope webhook.write.
responses:
'204':
description: Webhook cancelled.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v2/webhook:
get:
operationId: listWebhooks
tags:
- Pix Webhooks
summary: List Pix webhooks
description: Lists webhooks associated with Pix keys, filtered by parameters. Scope webhook.read.
responses:
'200':
description: A list of webhooks.
content:
application/json:
schema:
type: object
properties:
webhooks:
type: array
items:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/authorize:
post:
operationId: cobrancasAuthorize
tags:
- Authorization
summary: Obtain a Cobranças API access token
description: >-
OAuth2 client-credentials token endpoint for the Cobranças host. Send
HTTP Basic auth with Client_Id and Client_Secret. No mTLS certificate is
required for this host.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRequest'
responses:
'200':
description: Access token issued.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/charge:
post:
operationId: createCharge
tags:
- Cobranças
summary: Create a charge (two-step)
description: Creates a charge (transação) describing the item(s), value, and quantity, before associating a payment method.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChargeRequest'
responses:
'200':
description: The created charge.
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/charge/one-step:
post:
operationId: createChargeOneStep
tags:
- Cobranças
summary: Create a charge (one-step)
description: Creates a charge and associates the payment method (boleto, card, or Pix) in a single request.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChargeOneStepRequest'
responses:
'200':
description: The created charge with payment details.
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/charges:
get:
operationId: listCharges
tags:
- Cobranças
summary: List charges
description: Returns issued charges, filterable by charge_type and date range (begin_date, end_date).
parameters:
- name: charge_type
in: query
required: false
description: Filter by charge type (for example billet or carnet).
schema:
type: string
- name: begin_date
in: query
required: false
schema:
type: string
format: date
- name: end_date
in: query
required: false
schema:
type: string
format: date
responses:
'200':
description: A list of charges.
content:
application/json:
schema:
$ref: '#/components/schemas/ChargeList'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/charge/{id}:
parameters:
- $ref: '#/components/parameters/ChargeId'
get:
operationId: getCharge
tags:
- Cobranças
summary: Retrieve a charge
description: Returns information for a single charge (transação) by id.
responses:
'200':
description: The requested charge.
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/charge/{id}/pay:
parameters:
- $ref: '#/components/parameters/ChargeId'
post:
operationId: payCharge
tags:
- Cobranças
summary: Associate a payment method to a charge
description: Associates a charge with the desired payment method (boleto bancário, credit card, or Pix).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PayChargeRequest'
responses:
'200':
description: The charge with payment details.
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/charge/{id}/billet:
parameters:
- $ref: '#/components/parameters/ChargeId'
put:
operationId: updateChargeBilletDueDate
tags:
- Cobranças
summary: Change a charge's boleto due date
description: Alters the expiration (vencimento) date of a boleto charge.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
expire_at:
type: string
format: date
responses:
'200':
description: The updated charge.
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/charge/{id}/cancel:
parameters:
- $ref: '#/components/parameters/ChargeId'
put:
operationId: cancelCharge
tags:
- Cobranças
summary: Cancel a charge
description: Cancels an existing charge.
responses:
'200':
description: The cancelled charge.
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/charge/{id}/settle:
parameters:
- $ref: '#/components/parameters/ChargeId'
put:
operationId: settleCharge
tags:
- Cobranças
summary: Manually settle a charge
description: Marks a charge as paid (baixa manual).
responses:
'200':
description: The settled charge.
content:
application/json:
schema:
$ref: '#/components/schemas/Charge'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/carnet:
post:
operationId: createCarnet
tags:
- Carnê
summary: Create a carnê
description: Creates a carnê - a set of installment charges (parcelas) generated in a batch.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CarnetRequest'
responses:
'200':
description: The created carnê.
content:
application/json:
schema:
$ref: '#/components/schemas/Carnet'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/carnet/{id}:
parameters:
- $ref: '#/components/parameters/CarnetId'
get:
operationId: getCarnet
tags:
- Carnê
summary: Retrieve a carnê
description: Returns information for an existing carnê by id.
responses:
'200':
description: The requested carnê.
content:
application/json:
schema:
$ref: '#/components/schemas/Carnet'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v1/carnet/{id}/parcel/{parcel}:
parameters:
- $ref: '#/components/parameters/CarnetId'
- name: parcel
in: path
required: true
description: The installment (parcela) number.
schema:
type: integer
put:
operationId: updateCarnetParcelDueDate
tags:
- Carnê
summary: Change a parcel's due date
description: Alters the expiration date of a specific carnê parcel.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
expire_at:
type: string
format: date
responses:
'200':
description: The updated carnê.
content:
application/json:
schema:
$ref: '#/components/schemas/Carnet'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/carnet/{id}/cancel:
parameters:
- $ref: '#/components/parameters/CarnetId'
put:
operationId: cancelCarnet
tags:
- Carnê
summary: Cancel a carnê
description: Cancels an entire carnê and all of its open parcels.
responses:
'200':
description: The cancelled carnê.
content:
application/json:
schema:
$ref: '#/components/schemas/Carnet'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/carnet/{id}/settle:
parameters:
- $ref: '#/components/parameters/CarnetId'
put:
operationId: settleCarnet
tags:
- Carnê
summary: Manually settle a carnê
description: Marks an entire carnê as paid (baixa manual).
responses:
'200':
description: The settled carnê.
content:
application/json:
schema:
$ref: '#/components/schemas/Carnet'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/oauth/token:
post:
operationId: openFinanceAuthorize
tags:
- Authorization
summary: Obtain an Open Finance API access token
description: >-
OAuth2 client-credentials token endpoint for the Open Finance host. Send
HTTP Basic auth with Client_Id and Client_Secret. This request also
requires the mTLS client certificate.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TokenRequest'
responses:
'200':
description: Access token issued.
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/open-finance/participants:
get:
operationId: listOpenFinanceParticipants
tags:
- Open Finance
summary: List Open Finance participants
description: >-
Lists the banks and fintechs available as payment sources in Brazil's
Open Finance ecosystem. Modeled from Efí's documented Open Finance
scopes (gn.opb.participants.read); path shown is representative.
Scope gn.opb.participants.read.
responses:
'200':
description: A list of participants.
content:
application/json:
schema:
type: object
properties:
participants:
type: array
items:
$ref: '#/components/schemas/Participant'
'401':
$ref: '#/components/responses/Unauthorized'
/v1/open-finance/payments/pix:
post:
operationId: initiateOpenFinancePix
tags:
- Open Finance
summary: Initiate a Pix payment via Open Finance
description: >-
Initiates a Pix payment as a payment initiator across an Open Finance
participant. Modeled from Efí's documented scope
gn.opb.payment.pix.send; path shown is representative.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OpenFinancePixRequest'
responses:
'201':
description: The initiated payment.
content:
application/json:
schema:
$ref: '#/components/schemas/OpenFinancePixPayment'
'401':
$ref: '#/components/responses/Unauthorized'
components:
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.
parameters:
Txid:
name: txid
in: path
required: true
description: Transaction identifier (26-35 alphanumeric characters).
schema:
type: string
ChargeId:
name: id
in: path
required: true
description: The charge (transação) identifier.
schema:
type: integer
CarnetId:
name: id
in: path
required: true
description: The carnê identifier.
schema:
type: integer
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'
schemas:
Error:
type: object
properties:
nome:
type: string
mensagem:
type: string
error:
type: string
error_description:
type: string
TokenRequest:
type: object
properties:
grant_type:
type: string
default: client_credentials
TokenResponse:
type: object
properties:
access_token:
type: string
token_type:
type: string
example: Bearer
expires_in:
type: integer
scope:
type: string
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
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
CobList:
type: object
properties:
parametros:
type: object
additionalProperties: true
cobs:
type: array
items:
$ref: '#/components/schemas/Cob'
CobvRequest:
type: object
properties:
calendario:
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/efi-bank/refs/heads/main/openapi/efi-bank-openapi.yml