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 18 days ago