Webhook do Pix
Por meio do webhook, notificamos nossos clientes sobre a validação de chaves, pagamentos, recebimentos, restituições, devoluções e entrega de comprovantes.
Eventos notificados
Abaixo listamos os eventos em que notificamos:
| Evento | Descrição |
|---|---|
| Pagamento | Este evento de notificação ocorrerá quando houver finalização do fluxo de pagamento, com a informação do status final da transação |
| Recebimento | Este evento de notificação ocorrerá quando houver um recebimento ou restituição for finalizado com sucesso na conta do cliente API |
| Devolução | Este evento de notificação ocorrerá quando houver finalização do fluxo de devolução, com a informação do status final da transação |
| Validação de Chaves | Este evento de notificação ocorrerá em resposta à API de validação de chaves, informando se a chave é válida |
| Solicitação de Comprovante | Este evento de notificação ocorrerá em resposta à solicitação de comprovantes de pagamento ou devolução realizada na funcionalidade Comprovantes de Pagamento e Devolução. |
| FalhaPagamentoAsync | Este evento de notificação ocorrerá quando houver alguma falha durante o processamento do pagamento assíncrono Solicitação de pagamento assíncrona. |
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 responder a notificação, o envio do webhook é cancelado;
- Podem ocorrer falhas, por isso, é importante que seja implementado um mecanismo de fallback para a realização de consulta das transações via API;
- Recomendamos que os eventos sejam tratados com idempotência, pois, eventualmente, a mesma mensagem poderá ser enviada mais de uma vez, e a falta desse tipo de tratamento pode trazer consequências sérias, tais como pagamentos em duplicidade, impressão de recebimento em dobro e outras.
Cadastro de rota
É necessário que o cliente cadastre uma rota acessível na internet para receber as notificações do webhook.
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 evento que deseja receber, com as opções Pagamento, Recebimento, DevolucaoEfetuada e ValidacaoChaves | array of strings | Sim |
| autorizacao | Mecanismo de segurança que o Banco BS2 utilizará para enviar o webhook. Enumeração: none, basic ou bearer | object | Sim |
Como resposta, enviamos status de sucesso (família HTTP 200).
Nota:
Podem ser personalizadas URLs distintas para cada evento de notificação. Uma notificação será enviada cada vez que ocorrer um evento, na conta configurada.
A conta definida na configuração, é obtida através do contexto em que o access_token utilizado na requisição foi gerado.
Registro do certificado DNS
Após cadastrar o webhook é preciso registrar o certificado do DNS da rota parametrizada.
A funcionalidade Webhook - Certificado - Inclusão/Atualização atualiza o certificado para todas as rotas configuradas. Já o método Webhook - Certificado - Inclusão/Atualização por ID permite selecionar uma rota específica e realizar a atualização do certificado.
Solicitamos os campos:
| Campo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| configuracaoId | Identificador do webhook configurado | string | Sim |
| certificado | Enviar o certificado X.509 codificado em base64 da rota do seu webhook (Arquivo *.cer) | string | Sim |
Como resposta, enviamos status de sucesso HTTP 204.
Mais detalhes de como configurar o DNS no link Como exportar DNS.
Obtenção das configurações
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 evento cadastrado na rota, com as opções Pagamento, Recebimento, DevolucaoEfetuada e ValidacaoChaves | string | Não |
| contaNumero | Número da conta vinculada ao webhook | integer | Não |
| somenteComTxId | obsoleto, não utilizar | - | - |
| url | URL cadastrada para receber o evento | string | Sim |
| autorizacao | Mecanismo de segurança que o Banco BS2 utilizará para enviar o webhook. Enumeração: none, basic ou bearer | object | Sim |
Exclusão de configuração de notificação
Essa funcionalidade permite excluir uma notificação configurada.
Solicitamos os campos:
| Tipo | Descrição | Formato | Obrigatório |
|---|---|---|---|
| configuracaoId | Identificador do webhook configurado | string | Sim |
Como resposta, enviamos status de sucesso HTTP 204.
Obtenha o Id pelo método Webhook - Obter
Exemplos de retorno do Webhook
A seguir, detalhamos os campos dos contratos que serão enviados nas notificações.
Recebimento / Restituição
Nas notificações de recebimento e restituição (evento Recebimento), enviamos as informações:
| Campo | Descrição | Formato |
|---|---|---|
| EndToEndId | Identificador da transação Pix | string |
| txid | Identificador da transação com a finalidade de conciliação | string |
| Valor | Valor da transação | double |
| Horario | Data e hora em que a transação foi efetivada | date-time |
| Pagador | Objeto contendo dados do pagador | object |
| Pagador.Cpf | Documento CPF/CNPJ do pagador | string |
| Pagador.Nome | Nome do pagador | string |
| InfoPagador | Mensagem informada pelo pagador para o recebedor | string |
| Devolucoes | Dados preenchidos quando se trata de restituição, ou seja, devolução a crédito na conta do cliente | object |
| Devolucoes.Id | Identificador da restituição gerado pelo Banco BS2 | string |
| Devolucoes.RtrId | Identificador da transação de restituição | string |
| Devolucoes.Valor | Valor da restituição | double |
| Devolucoes.Horario | Horário da restituição | date-time |
| Devolucoes.Status | Status da restituição, que será efetivado | string |
| Status | Status da transação de recebimento, que será efetivado | string |
| Motivo | Motivo é informado pela contraparte em caso de restituição | string |
Pagamento
Nas notificações de pagamento, enviamos os campos:
| Campo | Descrição | Formato |
|---|---|---|
| Status | Status do pagamento, conforme tabela Status Pagamento | string |
| PagamentoId | Identificador único do pagamento | string |
| Erro | Objeto com descrição do erro, se ocorrer | objeto |
| Erro.Codigo | Código do erro | string |
| Erro.Descricao | Descrição do erro | string |
| EndToEndId | Identificador da transação | string |
| EndToEndIdOrigem | Identificador do pagamento que originou a devolução | string |
| Valor | Valor do pagamento | decimal |
| Data | Data do pagamento | date-time |
| CampoLivre | Mensagem destinada ao recebedor | string |
| Pagador | Objeto contendo os dados do pagador | object |
| Pagador.Nome | Nome do pagador | string |
| Pagador.NomeFantasia | Nome fantasia do pagador | string |
| Pagador.Documento | CPF/CNPJ do pagador | string |
| Pagador.Ispb | ISPB do pagador | string |
| Pagador.Agencia | Agência bancária do pagador | string |
| Pagador.Conta | Conta do pagador | string |
| Pagador.ContaTipo | Tipo de conta do pagador | string |
| Pagador.ChaveDict | Chave Pix | string |
| Recebedor | Objeto contendo os dados do recebedor | object |
| Recebedor.Nome | Nome do recebedor | string |
| Recebedor.NomeFantasia | Nome fantasia do recebedor | string |
| Recebedor.Documento | CPF/CNPJ do recebedor | string |
| Recebedor.Ispb | ISPB do recebedor | string |
| Recebedor.Agencia | Agência bancária do recebedor | string |
| Recebedor.Conta | Conta do recebedor | string |
| Recebedor.ContaTipo | Tipo de conta do recebedor | string |
| Recebedor.ChaveDict | Chave Pix | string |
| SolicitacaoId | Identificador da solicitação de pagamento gerado pelo Banco BS2 | guid |
| Reenvio | Objeto contendo informações do envio da notificação | object |
| Reenvio.UltimoEnvioId | identificador do último envio da notificação | string |
| Reenvio.Tentativa | Quantidade de tentativas de envio da notificação | string |
Devolução
Nas notificações de recebimento, enviamos os campos:
| Campo | Descrição | Formato |
|---|---|---|
| dataHoraCriacao | Data e hora da criação da devolução | date-time |
| IdDevolucao | Identificador da devolução | string |
| ValorDevolucao | Valor da devolução | double |
| CodigoMotivo | Código do motivo de devolução, conforme tabela [Motivo devolução] | string |
| MotivoDevolucao | Descrição do motivo de devolução, conforme tabela [Motivo devolução] | string |
| E2Eoriginal | Identificador da mensagem que originou a devolução | string |
| bancoRecebedor | Banco recebedor da devolução | string |
| bancoPagador | Banco pagador da devolução | string |
Validação de chaves
Nas notificações de validação de chaves, enviamos os campos:
| Campo | Descrição | Formato |
|---|---|---|
| Id | Identificador da validação de chave | guid |
| Chave | Chave Pix | string |
| Valida | Determina se a chave é válida (True) ou inválida (False) | boolean |
Pagamento assíncrono
Nas notificações em caso de falha do pagamento assíncrono, enviamos os campos:
| Campo | Descrição | Formato |
|---|---|---|
| chave | chave informada na requisição | guid |
| mensagem | Descreve a falha que ocorreu durante o processamento da requisição | string |
| documento | Documento informado na requisição, se tiver sido informado | boolean |
| solicitacaoId | Identificador da solicitação de pagamento retornada para o cliente | guid |
| pagamentoId | Identificador do pagamento | guid |
Comprovante de pagamento
Nas notificações em caso de falha do pagamento assíncrono, enviamos os campos:
| Campo | Descrição | Formato |
|---|---|---|
| identificadorTransação | EndToEnd ou rtrId da transação solicitada | guid |
| idComprovante | Identificador da notificação respondida na solicitação; | string |
| arquivo | arquivo em PDF com os dados do comprovante; |
Updated 9 days ago