Webhook do Pix
Por meio do webhook, notificamos nossos clientes sobre os pagamentos e recebimentos Pix.
Criando uma rota
É necessário que o cliente cadastre uma rota acessível na internet para receber as notificações do webhook.
Podem ser cadastradas rotas para cada tipo de evento transacional, conforme listado abaixo, ou uma rota para receber todos os eventos.
Atualmente notificamos os seguintes eventos:
| Tipo | Descrição | Callback |
|---|---|---|
| Pagamento | Ocorre toda vez que um pagamento é realizado com sucesso | Pagamento - Consultar - PagamentoId |
| Recebimento | Ocorre toda vez que uma transação Pix é recebida em conta com sucesso. | Recebimento - Consultar por EndToEndId |
| ValidacaoChaves | Ocorre como resposta da API de validação de chaves, informando se a chave é válida ou não | - |
Por meio do contrato abaixo será possível cadastrar o webhook desejado.
Solicitamos os campos:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| url | URL do cliente que receberá o evento quando disparado de acordo com a regra de negócio do evento | string | Sim |
| eventos | Tipo de envento que deseja receber, com as opções "Pagamento", "Recebimento" e "ValidacaoChaves" | array | Sim |
| autorizacao | Mecanismo de segurança que o Banco BS2 utilizará para enviar o webhook. Enum: "none" "basic" "bearer" | object | Sim |
Como resposta, enviamos status de sucesso (família HTTP 200).
Importante:
- Realizamos algumas tentativas de reenvio do webhook, e após quantidade de tentativas, os reenvios cessam;
- Se a URL cadastrada demorar mais de 1000ms para receber a notificação, o envio do webhook é cancelado;
- Ressaltamos que: falhas podem ocorrer em ambos os lados (Banco BS2 ou cliente). Por isso, é importante que seja configurado um mecanismo de callback nas APIs de consulta de transação.
Registrando o certificado DNS
Após cadastrar o webhook é preciso registrar o certificado do DNS da rota parametrizada. E essa ação deve ser realizada por meio do método Webhook - Certificado - Inclusão/Atualização.
Solicitamos o campo:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| certificado | Enviar o certificado X.509 codificado em base64 da rota do seu webhook (Arquivo *.cer) | string | Sim |
Como resposta, enviamos status de sucesso (família HTTP 200).
Mais detalhes de como configurar o DNS no link Como registrar DNS.
Obtendo configurações do webhook
Retornamos as configurações de todos os webhooks cadastrados em todas as contas do cliente.
Resposta:
| Tipo | Descrição | Formato | Nullable |
|---|---|---|---|
| id | Identificador único do webhook | string | Sim |
| evento | Tipo de envento que deseja receber, com as opções "Pagamento", "Recebimento" e ValidacaoChaves | string | Não |
| contaNumero | Número da conta vinculada ao webhook | integer | Não |
| somenteComTxId | Dado obsoleto | - | - |
| url | URL cadastrada para receber o evento | string | Sim |
| autorizacao | Mecanismo de segurança que o Banco BS2 utilizará para enviar o webhook. Enum: "none" "basic" "bearer" | object | Sim |
Excluindo o Webhook
Essa funcionalidade permite excluir um webhook configurado.
Solicitamos os campos:
| Tipo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| Id | Identificador do webhook configurado | string | Sim |
Como resposta, enviamos status de sucesso (família HTTP 200).
Obtenha o Id pelo método Webhook - Obter
Exemplos de retorno do Webhook
A seguir, detalhamos os possíveis status que poderão ser retornados via webhook, nas transações de pagamento e recebimento.
Recebimento
Para as operações de recebimento, o status poderá ser:
| Status | Descrição |
|---|---|
| EFETIVADO | A transação de recebimento foi efetivada |
{"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}]}
Pagamento
Para as operações de pagamento, os status poderão ser:
| Código | Status | Descrição |
|---|---|---|
| 3 | EFETIVADO | Pagamento foi realizado com sucesso e o valor foi debitado da conta |
| 4 | REJEITADO | A contraparte do pagamento rejeitou a transação. Os motivos podem variar desde indisponibilidade na contraparte ou conta do destinatário encerrada/bloqueada. |
{"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 1 month ago