--- updatedAt: 2025-04-15T20:19:28.000Z agentTools: projectIndex: https://devs.bs2.com/llms.txt --- # 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](https://devs.bs2.com/reference/get_pix-direto-forintegration-v1-pagamentos-pagamentoid) | | Recebimento | Occurs every time a Pix transaction is successfully received into the account | [Recebimento - Consultar por EndToEndId](https://devs.bs2.com/reference/get_pix-direto-forintegration-v1-recebimentos-endtoendid-recebimento) | # 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). [Webhook - Criar/Atualizar](https://devs.bs2.com/reference/put_pix-direto-forintegration-v1-webhook-bs2) # > ⚠️ Important: > > 1. We made some attempts to resend the webhook, and after a number of attempts, the resends cease; > 2. If the registered URL takes more than 1000ms to receive the notification, the webhook sending is canceled; > 3. **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](https://devs.bs2.com/reference/put_pix-direto-forintegration-v1-webhook-bs2-certificado) 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](https://devs.bs2.com/docs/como-registrar-dns-copy). # ## 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
[Webhook - Obter](https://devs.bs2.com/reference/get_pix-direto-forintegration-v1-webhook-bs2) # ## 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](https://devs.bs2.com/reference/get_pix-direto-forintegration-v1-webhook-bs2) 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 | # ```json {"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 | # ```json {"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":"matheus221@gmail.com"},"SolicitacaoId":null,"Reenvio":{"UltimoEnvioId":"00000000-0000-0000-0000-000000000000","Tentativa":0}} ```