Pix Flow (outgoing)
Payments, once confirmed by the paying customer, occurs in four stages: a) first - communication from the indirect party to the liquidator; b) second and third - communication between the liquidator and the SPI; and c) notification from the liquidator to the indirect party with the result of the operation, which may be complete, incomplete due to some business rule or even due to some operational failure.
For this reason, the direct or indirect party will never be able to know that the next level stage means that the transfer has been made. We need to wait for the end of the payment cycle to be sure.
Payment Initiation
Payment initiation is the step involving the preparation of the information and making it available for the end user to, based on their analysis, confirm their payment sending operation. This will originate the record that, once confirmed, will effectively be forwarded to the SPI.
Initiation can take place in four different ways:
Initiation with DICT (Directory of Transactional Account Identifiers) Key
When initiating a payment with DICT Key, the following flow must be in place:
- DICT A - Check Internal DICT
- If the Pix key is found in the Internal DICT, it means that the recipient is an account holder at the institution itself. In this case, participant must process internal settlement (OUT5). In other words, they must debit and credit the accounts in its own system. In this case, they should not forward the settlement to the liquidator, but notify its customers (OUT13, IN9), and finalize the flow;
- If the key is not found in the Internal DICT, you should search for it in DICT B (liquidator), and move on with the flow;
Important:
Internal settlements must be reported to BACEN through file 1201, which will be discussed later in this document.
- DICT B - Check the settling DICT
- If the key is not found in the settling DICT, please notify the paying user and go ahead with the flow, before the confirmation stage;
- If the settling DICT key is found, please return the recipient's information (according to the Pix – BACEN user experience manual). From this moment on, payment can now be confirmed.
Important:
This is when the BACEN DICT key scanning prevention mechanism begins for the first time, as all the tokens are deleted from the participant's Bucket: 1 token for a key found in the DICT and 3 tokens for a key that is not found.
It is essential that indirect participants control their own token bucket in order to avoid rate limit errors.
Check the DICT Operational Manual to follow BACEN regulations regarding this topic https://www.bcb.gov.br/estabilidadefinanceira/pix?modalAberto=regulamentacao_pix.
Initiation can take place in four different ways:
Field | Description | Format | Mandatory |
---|---|---|---|
pagador | Payer data (bank, branch, account, document) | object | No |
chave | Value and type of the recipient's DICT Key, as shown in the table Types of keys | object | No |
openFinance | If the initiation begins from an ITP (payment initiator within Open Finance), please enter the Pix transaction identifier and CNPJ of the payment initiator here | object | No |
campoLivre | Message to recipient | string | No |
dataAgendamento | Transaction scheduling date, if scheduled | date | No |
Response:
Field | Description | Format | Nullable |
---|---|---|---|
pagamentoId | Payment identifier generated by Banco BS2 | string | No |
endToEndId | Unique transaction identifier | string | Yes |
criadoEmUtc | Transaction creation date | date-time | No |
status | Status of the payment transaction, as shown in the table Payment Status | string | No |
pagador | Payer data (bank, branch, account, document) | object | No |
recebedor | Recipient data (bank, branch, account, document) | object | No |
Iniciação de pagamento por chave Pix
Initiation using bank details
Initiating payment using bank details (OUT1) is similar to a regular bank transfer (TED) and basically consists of informing the recipient's BANK, BRANCH, ACCOUNT TYPE, ACCOUNT NUMBER and DOCUMENT.
We recommend that participants validate the Bank and Branch information, using a dedicated local registry or service, and validate the document number (CPF or CNPJ). Once everything is validated, show it to the paying user and await PAYMENT CONFIRMATION.
Important:
At initiation time, there is no way to validate the existence of the recipient's account, the type of account or even whether the recipient's document number are as reported at the moment. These data will be validated, after confirmation, by the receiving institution.
The following fields are required:
Field | Description | Format | Mandatory |
---|---|---|---|
pagador | Pix payer data (bank, branch, account, document) | object | Yes |
recebedor | Pix recipient data (bank, branch, account, document) | object | Yes |
openFinance | If the initiation begins from an ITP (payment initiator within Open Finance), please enter the Pix transaction identifier and CNPJ of the payment initiator here | object | Yes |
campoLivre | Message to recipient | string | No |
dataAgendamento | Transaction scheduling date, if scheduled | date | Yes |
Resposta:
Field | Description | Format | Nullable |
---|---|---|---|
pagamentoId | Payment identifier generated by Banco BS2 | string | No |
endToEndId | Unique transaction identifier | string | Yes |
criadoEmUtc | Transaction creation date | date-time | No |
status | Status of the payment transaction, as shown in the table Payment Status | string | No |
pagador | Pix payer data (bank, branch, account, document) | object | No |
recebedor | Pix recipient data (bank, branch, account, document) | object | No |
Iniciação de pagamento por dados manuais
Initiation by scanning a QR CODE or using a 'copy and paste' code
Scanning a QR CODE, using the institution's app or even by a dedicated device, gives you a sequence of characters in return, which is known as QR-CODE CHARACTERS. Once you have obtained this code, you can move on to initiation.
When it comes to the QR CODE Copy and Paste procedure, as the code is already known, scanning will not be necessary to allow for the initiation stage.
Initiation using QR CODE
In static or dynamic QR CODE initiation, the following fields are required:
Field | Description | Format | Mandatory |
---|---|---|---|
pagador | Payer data (bank, branch, account, document) | object | Yes |
openFinance | If the initiation begins from an ITP (payment initiator within Open Finance), please enter the Pix transaction identifier and CNPJ of the payment initiator here | object | Yes |
qrcode | QR CODE CHARACTERS with billing information | string | No |
transactionId | Code provided by the customer when generating the QR CODE and which will be used by the customer to identify the payment | string | No |
campoLivre | Message to recipient | string | No |
dataAgendamento | Transaction scheduling date, if scheduled | date | No |
Resposta:
Field | Description | Format | Nullable |
---|---|---|---|
pagamentoId | Payment identifier generated by Banco BS2 | string | No |
endToEndId | Transaction identifier | string | Yes |
criadoEm | Payment creation date | date-time | No |
situacao | Status of the payment transaction, as shown in the table Payment Status | string | No |
pagador | Payer data (bank, branch, account, document) | object | No |
recebedor | Recipient data (bank, branch, account, document) | object | No |
qrCode | QR CODE billing information (amount, Pix key, description, etc.) | object | No |
Iniciação de pagamento por QRCode
View Payments
Using the features below, you can view payments using endToEnd or payment identifier.
Payment view by Id or EndToEndId
In this functionality, you will view a payment from an endToEndId or payment ID entered.
The following fields are required:
Field | Description | Format | Mandatory |
---|---|---|---|
Id | Payment identifier generated by Banco BS2 | string | Yes, if the EndToEndId has not been entered |
EndToEndId | Transaction identifier | string | Yes, if the Id has not been entered |
Response:
Field | Description | Format | Nullable |
---|---|---|---|
Id | Payment identifier generated by Banco BS2 | string | No |
endToEndId | Transaction identifier | string | Yes |
transactionId | Billing identifier, when initiated by QR CODE | string | Yes |
solicitadoEmUtc | Date and time payment was requested by the payer | date-time | No |
enviadoEmUtc | Date and time payment is made for settlement | date-time | Yes |
valor | Transaction amount | double | Yes |
descricaoPagamento | Message to recipient | string | Yes |
tipoPagamento | Type of payment initiation, as per table Types of payment | string | No |
chave | Recipient’s DICT key value | string | Yes |
qrCode | QR CODE’s copy and paste code | string | Yes |
status | Status of the payment transaction, as shown in the table Payment Status | string | No |
finalidade | Purpose of transaction, as shown in the table Purpose of transaction | string | No |
prioridade | Priority of transaction, as shown in the table Transaction Priority | string | No |
tipoPrioridade | Type of transaction priority, as shown in the table Type of Priority | string | Yes |
valorSaqueOuTroco | Withdrawal or change for Pix Saque and Pix Troco | double | Yes |
ispbFacilitadorServicoSaqueOuTroco | Bank code provided for the service, in case of Pix Saque and Pix Troco | string | Yes |
modalidadeAgente | Type of withdrawal agent in the case of a Pix Saque and Pix Troco transaction, according to the table Type of Agent | string | No |
cnpjIniciador | CNPJ of payment initiator | string | Yes |
pagador | Payer data (bank, branch, account, document) | object | No |
recebedor | Recipient data (bank, branch, account, document) | object | No |
cobranca | Billing information (id, payer, expiration date, value, key, etc.) | object | No |
restituicoes | View returns associated with payment, if any | array | Yes |
motivoRejeicao | Code and description of the reason for denying the transaction that was informed by BACEN in PACS002, if the payment was denied | object | No |
agendamento | Payment transaction scheduling details, if any | object | No |
erroEmUtc | In case of a transaction error, the date and time it occurred will be displayed | date-time | Yes |
erroDescricao | In case of a transaction error, a description of the error will be displayed | string | Yes |
Canceling payments
By using this functionality, you can cancel a payment transaction that has not yet been confirmed.
The following fields are required:
Field | Description | Format | Mandatory |
---|---|---|---|
pagamentoId | Payment identifier generated by Banco BS2 | string | Yes |
motivo | Reason for cancellation | string | No |
Response:
Field | Description | Format | Nullable |
---|---|---|---|
pagamentoId | Payment identifier | string | No |
canceladoEmUtc | Date and time of cancellation | date-time | No |
Updated 8 days ago