Payment
In this section, we provide operations to make payments and follow up their completion.
Payment - Check
This functionality allows checking payments made in a period and displays the status and other payment data.
We request the fields:
| Campo | Description | Format | Mandatory |
|---|---|---|---|
| Inicio | Start of desired search period | date-time | Yes |
| Fim | End of desired search period | date-time | Yes |
| Status | Payment status that is desired | string | No |
| Tipo | Type of payment initiation, which can be: CHAVE_DICT (DICT KEY), MANUAL or QR_CODE | string | No |
Response:
| Campo | Description | Format | Nullablle |
|---|---|---|---|
| pagamentoId | Payment identifier | string | No |
| endToEndId | Pix transaction identifier | string | Yes |
| dataHoraCriacao | Payment initiation date and time | date-time | No |
| pagador | Pix transaction payer data (bank, branch, account, document) | object | Yes |
| recebedor | Pix transaction receiver data (bank, branch, account, document) | object | Yes |
| informacoesEntreUsuarios | Information included by the payer, if desired, at the time of payment | string | Yes |
| status | Transaction status, see table [Payment Status] | string | No |
| valor | Pix transaction amount | number | No |
Payment - Check - Payment Id - PagamentoId
This functionality allows checking a specific payment using the internal identification of the payment in question and displays status and other payment data.
We request the fields:
| Field | Description | Format | Mandatory |
|---|---|---|---|
| pagamentoId | Payment identifier | string | Yes |
Response:
| Field | Description | Format | Nullablle |
|---|---|---|---|
| endToEndId | Pix transaction identifier | string | Yes |
| status | Transaction status, see table [Payment Status] | string | No |
| qrCode | QR CODE data (category, currency, country, city and txId) | object | Yes |
| cobranca | Collection data (Id, payer, due date, amount, key, etc.) | object | Yes |
| recebedor | Pix transaction receiver data | object | Yes |
| valor | Pix transaction amount | number | Yes |
| numeroContaPagador | Account number used in payment validation | string | Yes |
Pagamento - Consultar - PagamentoId
Payment - Start - QrCodes
This functionality validates the properties of a QR Code. Upon successful initiation, it will be possible to confirm payment in the operation Pagamento - Confirmar.
As a prerequisite, the QR Code cannot have been generated by the client's own account.
We request the fields:
| Field | Description | Format | Mandatory |
|---|---|---|---|
| qrCode | Data obtained by reading the QR Code or also known as the "Copy & Paste" code | string | Yes |
Response:
| Field | Description | Format | Nullablle |
|---|---|---|---|
| pagamentoId | Payment identifier | string | No |
| endToEndId | Pix transaction identifier | string | Yes |
| pagador | Pix payer data (bank, branch, account, document) | object | Yes |
| recebedor | Pix receiver data (bank, branch, account, document) | object | Yes |
| valor | Pix transaction amount | number | Yes |
| tipo | Type of QR CODE, whether "Static" or "Dynamic" | string | No |
| cobranca | Collection data (Id, payer, validity date, amount, key, etc.) | object | Yes |
| txId | Identifier provided by the client that identifies the transaction | string | Yes |
Payment - Start - Keys
This functionality validates a PIX key in the DICT* and, if agreed, allows payment to proceed. Upon successful initiation, it will be possible to confirm payment in the operation Pagamento - Confirmar.
As a prerequisite, the Pix key cannot be from the client's account.
We request the fields:
| Field | Description | Format | Mandatory |
|---|---|---|---|
| chave | Receiver's DICT key, see table [Types of keys] | object | Yes |
Response:
| Field | Description | Format | Nullablle |
|---|---|---|---|
| pagamentoId | Payment identifier | string | No |
| endToEndId | Pix transaction identifier | string | Yes |
| pagador | Pix payer data (bank, branch, account, document) | object | Yes |
| recebedor | Pix receiver data (bank, branch, account, document) | object | Yes |
*Directory of Transactional Account Identifiers
Important:
The Central Bank regulates access to the DICT for key verification through request limitation policies.
Therefore, it is important to preserve the process of initiating payments via keys so that there is no conduct that appears to scan keys.
See more at Token Bucket.
Payment - Start - Manual
This functionality validates the receiver's bank details. Upon successful initiation, it will be possible to confirm payment in the operation Pagamento - Confirmar.
We request the fields:
| Field | Description | Format | Mandatory |
|---|---|---|---|
| recebedor | Requests data from the Pix receiver (bank, branch, account, document) | object | Yes |
Response:
| Field | Description | Format | Nullablle |
|---|---|---|---|
| pagamentoId | Payment identifier | string | No |
| endToEndId | Pix transaction identifier | string | Yes |
| pagador | Pix payer data (bank, branch, account, document) | object | Yes |
| recebedor | Pix receiver data (bank, branch, account, document) | object | Yes |
Payment - Confirm
This functionality confirms the payment initiated through manual initiation operations, by QR CODE or keys. If the request is successful, a "Payment" event webhook will be triggered.
We request the fields:
| Field | Description | Format | Mandatory |
|---|---|---|---|
| pagamentoId | Payment identifier | string | Yes |
| recebedor | Pix receiver data (bank, branch, account, document) | object | Yes |
| valor | Payment amount | number | Yes |
| campoLivre | Message intended for the receiver | string | No |
| efetuarEm | Date on which payment will be made | date-time | No |
Response: HTTP 202 accepted.
Pagamento - Solicitação de pagamento
This functionality performs validation and verification in the DICT of a list of Pix keys for payment. And, valid keys have payments automatically initiated and confirmed.
Operations can be consulted individually in the functionality Pagamento - Consultar solicitacao por SolicitacaoId.
We request the fields:
| Field | Description | Format | Mandatory |
|---|---|---|---|
| solicitacoes | Pix key and amount to pay | object | Yes |
Response:
| Field | Description | Format | Nullablle |
|---|---|---|---|
| identificador | Individualized identifier for each payment made in the request | string | No |
| solicitacaoId | Payment request identification | string | Yes |
| chave | Pix key data | object | Yes |
| valor | Payment amount | object | Yes |
Pagamento - Iniciar pagamento por chave
Payment - Check request by Request id - SolicitacaoId
This functionality allows checking a specific payment by the payment request identification in question.
We request the field:
| Field | Description | Format | Mandatory |
|---|---|---|---|
| solicitacaoId | Payment request identifier | string | Não |
Response:
| Field | Description | Format | Nullable |
|---|---|---|---|
| solicitacaoId | Request identifier | string | No |
| pagamentoId | Payment identifier | string | No |
| endToEndId | Pix transaction identifier | string | No |
| status | Pix transaction status, see table [Payment Status] | string | No |
| agencia | Receiver's branch | string | No |
| numero | Receiver's account number | string | No |
| chave | Receiver's Pix Key | string | No |
| valor | Pix transaction amount | string | No |
| campoLivre | Message that the payer sends to the receiver, if desired | string | No |
| rejeitadoDescricao | Reason for rejection, in case of searching for rejected payments | string | No |
| erroDescricao | Reason for error, in case of payment error | string | No |
Pagamento - Consultar solicitacao por SolicitacaoId
Payment status
The table below displays the statuses that payments may present:
| Field | Description |
|---|---|
| INICIADO | Payment has been initiated, but has not yet been confirmed by the API consumer |
| CONFIRMADO | Confirmation was successful and the payment request was sent to BACEN |
| EFETIVADO | Payment was made successfully and the amount was debited from the account |
| REJEITADO | The payment counterparty rejected it. Reasons may vary from unavailability at the counterparty or receiver account closed/blocked |
| ERRO | An error occurred during the payment flow |
| EXPIRADO | The time between initiation and payment confirmation exceeded 12 hours |
Types of keys
Below is the table with the types of Pix keys and their formatting:
| Type | Regular Exp. | Example | Comment |
|---|---|---|---|
| CPF | ^[0-9]{11}$ | 12345678901 | |
| CNPJ | ^[0-9]{14}$ | 12345678901234 | |
| CNPJ | ^+[1-9][0-9]\d{1,14}$ | +5510998765432 | |
| E-mails válidos W3C HTML5 | [email protected] | Maximum 77 characters and in lowercase | |
| EVP | [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12} | 123e4567-e89b-12d3-a456-426655440000 | Virtual Payment Address is a type of key by DICT |
Updated 6 months ago