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:

PagamentoOccurs every time a payment is made successfullyPagamento - Consultar - PagamentoId
RecebimentoOccurs every time a Pix transaction is successfully received into the accountRecebimento - Consultar por EndToEndId
ValidacaoChavesOccurs 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:

urlURL of the client that will receive the event when triggered as per the event's business rulestringYes
eventosType of event you want to receive, with the options "Payment", "Receipt" and "Key Validation"arrayYes
autorizacaoSecurity mechanism that Banco BS2 will use to send the webhook. Enum: "none" "basic" "bearer"objectYes

In response, we send success status (HTTP family 200).

Webhook - Criar/Atualizar



  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 method.

We request the field:

certificadoSend the base64-encoded X.509 certificate of your webhook route (*.cer file)stringYes

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.

idUnique webhook identifierstringYes
eventoType of event you want to receive, with the options "Payment", "Receipt" and "Key Validation"stringNo
contaNumeroAccount number linked to the webhookintegerNo
somenteComTxIdObsolete data--
urlURL registered to receive the eventstringYes
autorizacaoSecurity mechanism that Banco BS2 will use to send the webhook. Enum: "none", "basic" or "bearer"objectYes

Webhook - Obter

Excluding the Webhook

This functionality allows excluding a configured webhook.

We request the fields:

IdConfigured webhook identificationstringYes

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.


For receipt operations, the status may be:

EFETIVADOThe 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}]}


For payment operations, the statuses may be:

3EFETIVADOPayment was made successfully and the amount was debited from the account
4REJEITADOThe 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}}