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:

TypeDescriptionCallback
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

Through the contract below it will be possible to register the desired webhook.

We request the fields:

FieldDescriptionFormatMandatory
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

⚠️

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

We request the field:

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

Excluding the Webhook

This functionality allows excluding a configured webhook.

We request the fields:

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

Receipt

For receipt operations, the status may be:

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

Payment

For payment operations, the statuses may be:

CodeStatusDescription
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}}