Pix webhook
Through the webhook, we notify our clients about Pix payments and receipts.
Creating a route
The client must register an accessible route on the internet to receive webhook notifications.
Routes can be registered for each type of transactional event, as listed below, or a route to receive all events.
We currently notify the following events:
| Type | Description | Callback |
|---|---|---|
| Pagamento | Occurs every time a payment is made successfully | Pagamento - Consultar - PagamentoId |
| Recebimento | Occurs every time a Pix transaction is successfully received into the account | Recebimento - Consultar por EndToEndId |
| ValidacaoChaves | Occurs as a response from the key validation API, informing whether the key is valid or not | - |
Through the contract below it will be possible to register the desired webhook.
We request the fields:
| Field | Description | Format | Mandatory |
|---|---|---|---|
| url | URL of the client that will receive the event when triggered as per the event's business rule | string | Yes |
| eventos | Type of event you want to receive, with the options "Payment", "Receipt" and "Key Validation" | array | Yes |
| autorizacao | Security mechanism that Banco BS2 will use to send the webhook. Enum: "none" "basic" "bearer" | object | Yes |
In response, we send success status (HTTP family 200).
Important:
- We made some attempts to resend the webhook, and after a number of attempts, the resends cease;
- If the registered URL takes more than 1000ms to receive the notification, the webhook sending is canceled;
- We emphasize that failures may occur on both sides (Banco BS2 or client). Therefore, it is important that a callback mechanism is configured in the transaction check APIs.
Registering the DNS certificate
After registering the webhook, it is necessary to register the DNS certificate of the parameterized route. And this action must be carried out using the Webhook - Certificado - Inclusão/Atualização method.
We request the field:
| Field | Description | Format | Mandatory |
|---|---|---|---|
| certificado | Send the base64-encoded X.509 certificate of your webhook route (*.cer file) | string | Yes |
In response, we send success status (HTTP family 200).
More details on how to configure DNS in the link How to register DNS.
Obtaining webhook configurations
We return the configurations for all webhooks registered in all client accounts.
Response:
| Type | Description | Format | Nullable |
|---|---|---|---|
| id | Unique webhook identifier | string | Yes |
| evento | Type of event you want to receive, with the options "Payment", "Receipt" and "Key Validation" | string | No |
| contaNumero | Account number linked to the webhook | integer | No |
| somenteComTxId | Obsolete data | - | - |
| url | URL registered to receive the event | string | Yes |
| autorizacao | Security mechanism that Banco BS2 will use to send the webhook. Enum: "none", "basic" or "bearer" | object | Yes |
Excluding the Webhook
This functionality allows excluding a configured webhook.
We request the fields:
| Type | Description | Format | Mandatory |
|---|---|---|---|
| Id | Configured webhook identification | string | Yes |
In response, we send success status (HTTP family 200).
Obtain the Id by the Webhook - Obter method.
Webhook return examples
Below, we detail the possible statuses that can be returned via webhook, in payment and receipt transactions.
Receipt
For receipt operations, the status may be:
| Status | Description |
|---|---|
| EFETIVADO | The receipt transaction has been completed |
{"pix":[{"EndToEndId":"E1823612020230914235911ccc399999","txid":"fd7599e5431741e666fdaaaa252d27a4","Valor":50.0,"Horario":"2023-09-14T20:50:51.90-03:00","Pagador":{"Cpf":"12358580208","Nome":"Matheus Nogueira Exemplo"},"InfoPagador":null,"Devolucoes":null,"Status":"EFETIVADO","Motivo":null}]}
Payment
For payment operations, the statuses may be:
| Code | Status | Description |
|---|---|---|
| 3 | EFETIVADO | Payment was made successfully and the amount was debited from the account |
| 4 | REJEITADO | The payment counterparty rejected the transaction. The reasons may vary from unavailability at the counterparty or the receiver's account being closed/blocked |
{"Status":3,"Erro":null,"EndToEndId":"E710278662023090523595556671111P","EndToEndIdOrigem":null,"Valor":25.0,"Data":"2023-09-15T21:00:00","CampoLivre":null,"Pagador":{"Nome":"PAGAMENTOS EXEMPLIFICADORES","NomeFantasia":null,"Documento":"44441227000111","Ispb":null,"Agencia":"0001","Conta":"18844744","ContaTipo":1,"ChaveDict":null},"Recebedor":{"Nome":"Matheus Oliveira Da Silva","NomeFantasia":null,"Documento":"10109222444","Ispb":null,"Agencia":"0001","Conta":"530440110","ContaTipo":4,"ChaveDict":"[email protected]"},"SolicitacaoId":null,"Reenvio":{"UltimoEnvioId":"00000000-0000-0000-0000-000000000000","Tentativa":0}}Updated about 2 months ago