Webhooks for indirect participants
The four types of Pix settlement operations - payments, receipts, returns and refunds - use webhooks in notifications of completion and validation of operations.
Therefore, indirect participants must have all their webhooks monitored, paying special attention to them, as the correct operation of these services is crucial to the success of the transaction.
We strongly recommend that indirect participants use routes that allow for them to be easily and quickly notified, and can respond in a timely manner to the completion and validation of operations, within the times provided for in the SLA.
Our notification service consists of a main cycle and a reprocessing cycle.
Main Cycle
The main cycle will always make a first delivery attempt, with a maximum wait of 300 milliseconds.
Retry Cycle
The Retry Cycle will be used for notifications that cannot be delivered in the main cycle.
Once the attempts are exhausted, the messages will be finalized and will not be used in the retry cycle again. However, they will be stored, and the indirect participant will not have access to the operation if the notifications are validated and/or without the final status notification of their operation in the case of notifications of completion.
Alternatively, in the case of outgoing transactions (Payments and Refunds), participants may make a query at any time Get Payments to recover payments, or Ger Refund to recover refunds, and upon refunding, update their bases.
For resource inflows (receipt and return), participants will need, in their internal processes, to confirm the operations by checking Ger receipt for receipt, and Get Return for return, and thus updating their records.
In transaction webhooks, we will send the minimum necessary so that participants can clearly identify which transaction the notification refers to.
Important:
Upon receipt and return, all data will be sent at the time of Validation.
As recommended by BACEN, all participants, including indirect participants and their end customers, need to treat all events with idempotency, as eventually the same message may be sent more than once and the lack of this type of treatment can have serious consequences, such as such as double payments, double receipt printing and others.
Necessary actions for indirect participants to receive notifications
Indirect participants will need to provide 07 (seven) routes so that BS2 can deliver notifications. They are as follows:
Notification of payment made
Participants will be notified when the payment flow is completed successfully (or not).
For this notification, we will send the following contract:
| Field | Description | Format | Nullable |
|---|---|---|---|
| chaveIdempotencia | Field that guarantees idempotence for participants to process the payment event. This allows participants to guarantee that they will not create two records for the same notification in case of a retry. | string | No |
| pagamentoId | Payment identifier generated by Banco BS2 | string | No |
| EndToEndId | Unique transaction identifier | string | No |
| valor | Transaction amount | double | No |
| status | Status of the payment transaction, as shown in the table Payment Status | string | No |
| solicitadoEmUtc | Date and time payment was requested by the payer | date-time | No |
| dataContabil | Accounting date for transaction | date-time | Yes |
| liquidadoEmUtc | Settlement date for transaction | date-time | Yes |
| rejeicao | Displays code and description the transaction was denied | object | Yes |
| erroDescricao | Displays the error description | string | Yes |
In response, we will wait for participants to send us the HTTP 2xx response to complete the notification and end the attempts.
In case of responses other than HTTP 2xx, we will try to resend notifications.
Endpoint para receber Webhook de Pagamento Finalizado
Notification of completed payments
Participants will be notified when the receipt flow is completed successfully (or not).
For this notification, we will send the following contract:
| Field | Description | Format | Nullable |
|---|---|---|---|
| chaveIdempotencia | Field that guarantees idempotence for participants to process the receipt event. This allows participants to guarantee that they will not create two records for the same notification in case of a retry. | string | Yes |
| transactionId | Billing transaction identifier | string | Yes |
| endToEndId | Unique transaction identifier | string | Yes |
| valor | Transaction amount | double | Não |
| status | Receipt status, as shown in the table Receipt status | string | Não |
| solicitadoEmUtc | Date and time receipt was sent by the payer | date-time | Yes |
| dataContabil | Transaction posting date | date-time | Yes |
| liquidadoEmUtc | Settlement date for transaction | string | Sim |
| motivoRejeicao | Displays code and description the transaction was denied | object | Não |
| erroDescricao | Displays description of the error, if an error occurred during receipt | string | Sim |
In response, we will wait for participants to send us the HTTP 2xx response to complete the notification and end the attempts.
In case of responses other than HTTP 2xx, we will try to resend notifications.
Endpoint para receber Webhook de Recebimento Finalizado
Notification of refund made
Participants will be notified when the refund flow is completed successfully (or not).
For this notification, we will send the following contract:
| Field | Description | Format | Nullable |
|---|---|---|---|
| chaveIdempotencia | Field that guarantees idempotence for participants to process the refund event. This allows participants to guarantee that they will not create two records for the same notification in case of a retry. | string | No |
| idExterno | Transaction identifier provided by participants when requesting the refund | string | Yes |
| endToEndId | Identifier of the payment that originated the refund | string | SiYesm |
| returnId | Refund transaction identifier | string | Yes |
| valor | Transaction amount | double | No |
| status | Status of refund, as shown in the table Status of refund | string | No |
| solicitadoEmUtc | Date and time the refund was requested by the recipient | date-time | No |
| dataContabil | Transaction posting date | date-time | Yes |
| liquidadoEmUtc | Settlement date for transaction | date-time | No |
| motivoRejeicao | Displays code and description the transaction was denied | object | Yes |
| erroDescricao | Displays the error description | string | Yes |
In response, we will wait for participants to send us the HTTP 2xx response to complete the notification and end the attempts.
In case of responses other than HTTP 2xx, we will try to resend notifications.
Endpoint para receber Webhook de Devolução Finalizada
Notification of return finalized
Participants will be notified when the return flow is completed successfully (or not).
For this notification, we will send the following contract:
| Field | Description | Format | Nullable |
|---|---|---|---|
| chaveIdempotencia | Field that guarantees idempotence for participants to process the return event. This allows participants to guarantee that they will not create two records for the same notification in case of a retry. | string | Yes |
| returnId | Return transaction identifier | string | Yes |
| endToEndId | Identifier of the payment that originated the return | string | Yes |
| valor | Transaction amount | double | No |
| status | Status of return, as shown in the table Status of return | string | No |
| solicitadoEmUtc | Date and time the return was requested by the recipient | date-time | Yes |
| dataContabil | Transaction posting date | date-time | Yes |
| liquidadoEmUtc | Settlement date for transaction | date-time | Yes |
| motivoRejeicao | Displays code and description the transaction was denied | object | Yes |
| erroDescricao | Displays the error description | string | Yes |
In response, we will wait for participants to send us the HTTP 2xx response to complete the notification and end the attempts.
In case of responses other than HTTP 2xx, we will try to resend notifications.
Endpoint para receber Webhook de Restituição do Pagamento Finalizada
Notification of receipt validation
A notification will be sent when a receipt is sent to the indirect participant through the Central Bank's primary message traffic channel. Banco BS2 will send the notification and wait for a timely response to complete the transaction within the agreed SLA.
For this notification, we will send the following contract:
| Field | Description | Format | Nullable |
|---|---|---|---|
| data | Date the Central Bank of Brazil sent the receipt request to Banco BS2 | date-time | No |
| endToEndId | Transaction identifier | string | Yes |
| transactionId | Unique receipt identifier generated by BS2 | string | Yes |
| CampoLivre | Message informed by the payer | string | Yes |
| cnpjIniciadorPagamento | CNPJ of the institution that initiated the payment, used in Open Banking | string | Yes |
| status | Status of the payment transaction, as shown in the table Payment Status | string | No |
| tipoIniciacao | Type of payment initiation in this case, as per table Types of initiation | string | No |
| finalidade | Purpose of transaction, as shown in the table Purpose of transaction | string | No |
| valor | Amount received | double | No |
| recebedor | Recipient details (bank, branch, account, document, etc.) | object | No |
| pagador | Payer details (bank, branch, account, document, etc.) | object | No |
| chaveDict | Pix key used to pay for the Pix transaction | string | Yes |
| prioridadeTransacao | Priority of transaction, as shown in the table Priority of transaction | string | No |
| tipoPrioridadeTransacao | Type of transaction priority, as shown in the table Type of Priority | string | No |
| valorSaqueOuTroco | Withdrawal or change when for Pix Saque and Pix Troco | double | Yes |
| ispbFacilitadorServicoSaqueOuTroco | ISPB of the Withdrawal or Change service facilitator | string | Yes |
| modalidadeAgente | Type of agent modality, as shown in the table Agent Modality | string | No |
In response, we will wait for participants to send us the HTTP 2xx response to complete the notification and end the attempts.
The response must contain the json with the following fields:
| Field | Description | Format | Nullable |
|---|---|---|---|
| transacaoAutorizada | This shows whether the indirect participant accepts (true) or rejects (false) the transaction | boolean | No |
| validacoes | List with error code and description objects, in case the participant rejects the return | array of objects | Yes |
Important:
For participants who wish to reject the return validation. the field
TransacaoAutorizadamust be equal tofalseand HTTP 2xx response.
In case of responses other than HTTP 2xx, we will try to resend notifications.
Webhook validação Recebimento - Cliente
Receipt validation notification on secondary channel
A notification will be sent when a receipt is sent to the participant through the Central Bank's secondary message traffic channel. Banco BS2 will send the notification and wait for a timely response to complete the transaction within the agreed SLA.
Note:
In the secondary channel, the total time for transaction settlement is up to 45 minutes, with the SPI having 15 minutes to process it and the recipient (direct and indirect participant) up to 30 minutes.
For this notification, we will send the following contract:
| Field | Description | Format | Nullable |
|---|---|---|---|
| data | Date the Central Bank sent the receipt request to Banco BS2 | date-time | No |
| endToEndId | Transaction identifier | string | Yes |
| transactionId | Unique receipt identifier generated by BS2 | string | Yes |
| campoLivre | Message informed by the payer | string | Yes |
| cnpjIniciadorPagamento | CNPJ of the institution that initiated the payment, used in Open Banking | string | Yes |
| status | Status of the payment transaction, as shown in the table Payment Status | string | No |
| tipoIniciacao | Type of payment initiation in this case, as per table Types of initiation | string | No |
| finalidade | Purpose of transaction, as shown in the table Purpose of transaction | string | No |
| valor | Amount received | double | No |
| recebedor | Pix recipient details (bank, branch, account, document, etc.) | object | No |
| pagador | Pix payer details (bank, branch, account, document, etc.) | object | No |
| chaveDict | Pix key used to pay for the Pix transaction | string | Yes |
| prioridadeTransacao | Priority of transaction, as shown in the table Priority of transaction | string | No |
| tipoPrioridadeTransacao | Type of transaction priority, as shown in the table Type of Priority | string | No |
| valorSaqueOuTroco | Withdrawal or change when for Pix Saque and Pix Troco | double | Yes |
| ispbFacilitadorServicoSaqueOuTroco | ISPB of the Withdrawal or Change service facilitator | string | Yes |
| modalidadeAgente | Type of agent modality, as shown in the table Agent Modality | string | No |
In response, we will wait for participants to send us the HTTP 2xx response to complete the notification and end the attempts.
The response must contain the json with the following fields:
| Field | Description | Format | Nullable |
|---|---|---|---|
| transacaoAutorizada | This shows whether the participant accepts (true) or rejects (false) the transaction | boolean | No |
| validacoes | List with error code and description objects, in case the participant rejects the return | array of objects | Yes |
Important:
For participants who wish to reject the return validation. the field
TransacaoAutorizadamust be equal tofalseand HTTP 2xx response.
In case of responses other than HTTP 2xx, we will try to resend notifications.
Webhook validação Recebimento - Cliente
Notification of return validation
A notification will be sent when a return is sent to the participant. Banco BS2 will send the notification and wait for a timely response to complete the transaction within the agreed SLA.
For this notification, we will send the following contract:
| Field | Description | Format | Nullable |
|---|---|---|---|
| returnId | Return transaction identifier | string | Yes |
| endToEndId | Identifier of the payment that originated the return | string | Yes |
| valor | Transaction amount | double | No |
| solicitadoEmUtc | Date and time receipt was sent by the payer | date-time | No |
| codigoDevolucao | Reason for refund code that will be sent in PACS004, as shown in the table Reasons for refund | string | No |
| tipoDevolucao | Type of refund, as shown in the table Type of refund | string | No |
| prioridadeTransacao | Priority of transaction, as shown in the table Priority of transaction | string | No |
| motivo | Message to recipient | string | Yes |
| ispbPagador | ISPB of paying bank | string | Yes |
| ispbRecebedor | ISPB of receiving bank | string | Yes |
In response, we will wait for participants to send us the HTTP 2xx response to complete the notification and end the attempts.
The response must contain the json with the following fields:
| Field | Description | Format | Nullable |
|---|---|---|---|
| transacaoAutorizada | This shows whether the participant accepts (true) or rejects (false) the transaction | boolean | No |
| validacoes | List with error code and description objects, in case the participant rejects the return | array of objects | Yes |
Important:
For participants who wish to reject the return validation. the field
TransacaoAutorizadamust be equal tofalseand HTTP 2xx response.
In case of responses other than HTTP 2xx, we will try to resend notifications.
Validação Síncrona da(s) Restituição(s) (Pagamento Restituido)
Updated 8 days ago