Webhooks para participantes indiretos
Os quatro tipos de operações de liquidação Pix, que são: pagamentos, recebimentos, devoluções e restituições, tem como elemento comum o uso de webhooks nas notificações de finalização e validação das operações.
Assim, o participante indireto deve ter, dentro de seus serviços monitorados, todos os seus webhooks, dedicando-lhe especial atenção, pois o correto funcionamento desses serviços é determinante para o sucesso do arranjo.
Recomendamos fortemente que o participante indireto utilize rotas que possam receber o mais rapidamente possível a notificação, e possa responder em tempo hábil as finalizações e validações das operações, dentro dos tempos previstos no SLA.
Nosso serviço de notificação é composto por um ciclo principal e outro de reprocessamento.
Ciclo principal
O ciclo principal sempre fará uma primeira tentativa de entrega, com espera máxima de 300 milissegundos.
Ciclos de retentativa
As notificações que não puderem ser entregues no ciclo principal entrarão no ciclo de retentativas.
Esgotadas as tentativas, as mensagens serão finalizadas e não voltarão para qualquer ciclo de retentativa, mas serão persistidas, ficando o participante indireto sem a operação no caso de notificações de validação e/ou sem a notificação final do status de sua operação em caso de notificações de finalização.
Alternativamente, em caso de operações de saída (Pagamentos e Devoluções), o participante poderá a qualquer tempo efetuar a consulta Obter Pagamentos para recuperar pagamentos, ou Obter devolução para recuperar devoluções, e a partir do retorno, atualizar suas bases.
Já nos fluxos de entrada de recursos (recebimento e restituição) os participantes precisarão, em seus processos internos de conciliação, confirmar as operações por meio da consulta Obter recebimento para recebimento, e consulta Obter restituição para restituição, atualizando seus controles a partir do retorno.
Nos webhooks de transação enviaremos o mínimo necessário para que o participante possa, de sua parte, identifica claramente a qual transação se refere a notificação.
Importante:
No recebimento e restituição, todos os dados serão mandados no momento da Validação.
Por recomendação do BACEN, todos os participantes, inclusive os indiretos e seus clientes finais, precisam tratar todos os eventos 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.
Implementações necessárias para que o indireto possa receber notificações
O indireto precisará disponibilizar 07 (sete) rotas para que o BS2 possa entregar as notificações. São elas:
Notificação de pagamento finalizado
Esta notificação ocorrerá quando o fluxo de pagamento for finalizado com sucesso ou não.
Para esta notificação enviamos o contrato a seguir:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| chaveIdempotencia | Campo que garante a idempotência para o participante processar o evento de pagamento. Dessa forma, o participante poderá garantir que não criará em seu ambiente dois registros para a mesma notificação em caso de retentativa | string | Não |
| pagamentoId | Identificador do pagamento gerado pelo Banco BS2 | string | Não |
| EndToEndId | Identificador único da transação | string | Não |
| valor | Valor da transação | double | Não |
| status | Status da transação de pagamento, conforme tabela Status do pagamento | string | Não |
| solicitadoEmUtc | Data e hora em que o pagamento foi solicitado pelo pagador | date-time | Não |
| dataContabil | Data contábil da transação | date-time | Sim |
| liquidadoEmUtc | Data da liquidação da transação | date-time | Sim |
| rejeicao | Apresenta o código e a descrição da rejeição | object | Sim |
| erroDescricao | Apresenta a descrição do erro | string | Sim |
Como resposta, aguardaremos que o participante nos envie a resposta HTTP 2xx para concluir a notificação e finalizar as tentativas.
Em caso de outras respostas que não sejam HTTP 2xx, haverá retentativas da notificação.
Endpoint para receber Webhook de Pagamento Finalizado
Notificação de recebimento finalizado
Esta notificação ocorrerá quando o fluxo de recebimento for finalizado com sucesso ou não.
Para esta notificação enviamos o contrato a seguir:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| chaveIdempotencia | Campo que garante a idempotência para o participante processar o evento de recebimento. Dessa forma, o participante poderá garantir que não criará em seu ambiente dois registros para a mesma notificação em caso de retentativa | string | Sim |
| transactionId | Identificador da transação da cobrança | string | Sim |
| endToEndId | Identificador único da transação | string | Sim |
| valor | Valor da transação | double | Não |
| status | Status do recebimento, conforme tabela Status do recebimento | string | Não |
| solicitadoEmUtc | Data e hora em que o recebimento foi enviado pelo pagador | date-time | Sim |
| dataContabil | Data da contabilização da transação | date-time | Sim |
| liquidadoEmUtc | Data da liquidação da transação em | string | Sim |
| motivoRejeicao | Apresenta o código e a descrição da rejeição | object | Não |
| erroDescricao | Apresenta a descrição do erro, se tiver ocorrido erro no recebimento | string | Sim |
Como resposta, aguardaremos que o participante nos envie a resposta HTTP 2xx para concluir a notificação e finalizar as tentativas.
Em caso de outras respostas que não sejam HTTP 2xx, haverá retentativas da notificação.
Endpoint para receber Webhook de Recebimento Finalizado
Notificação de devolução finalizada
Esta notificação ocorrerá quando o fluxo de devolução for finalizado com sucesso ou não.
Para esta notificação enviamos o contrato a seguir:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| chaveIdempotencia | Campo que garante a idempotência para o participante processar o evento de devolução. Dessa forma, o participante poderá garantir que não criará em seu ambiente dois registros para a mesma notificação em caso de retentativa | string | Não |
| idExterno | Identificador da transação informado pelo participante ao solicitar a devolução | string | Sim |
| endToEndId | Identificador do pagamento que originou a devolução | string | Sim |
| returnId | Identificador da transação de devolução | string | Sim |
| valor | Valor da transação | double | Não |
| status | Status da devolução, conforme tabela Status da devolução | string | Não |
| solicitadoEmUtc | Data e hora em que a devolução foi solicitada pelo recebedor | date-time | Não |
| dataContabil | Data da contabilização da transação | date-time | Sim |
| liquidadoEmUtc | Data da liquidação da transação | date-time | Não |
| motivoRejeicao | Apresenta o código e a descrição da rejeição | object | Sim |
| erroDescricao | Apresenta a descrição do erro | string | Sim |
Como resposta, aguardaremos que o participante nos envie a resposta HTTP 2xx para concluir a notificação e finalizar as tentativas.
Em caso de outras respostas que não sejam HTTP 2xx, haverá retentativas da notificação.
Endpoint para receber Webhook de Devolução Finalizada
Notificação de restituição finalizada
Esta notificação ocorrerá quando o fluxo de restituição for finalizado com sucesso ou não.
Para esta notificação enviamos o contrato a seguir:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| chaveIdempotencia | Campo que garante a idempotência para o participante processar o evento de RESTITUIÇÃO. Dessa forma, o participante poderá garantir que não criará em seu ambiente dois registros para a mesma notificação em caso de retentativa | string | Sim |
| returnId | Identificador da transação de restituição | string | Sim |
| endToEndId | Identificador do pagamento que originou a restituição | string | Sim |
| valor | Valor da transação | double | Não |
| status | Status da restituição, conforme tabela Status da devolução | string | Não |
| solicitadoEmUtc | Data e hora em que a restituição foi solicitada pelo recebedor | date-time | Sim |
| dataContabil | Data da contabilização da transação | date-time | Sim |
| liquidadoEmUtc | Data da liquidação da transação | date-time | Sim |
| motivoRejeicao | Apresenta o código e a descrição da rejeição | object | Sim |
| erroDescricao | Apresenta a descrição do erro | string | Sim |
Como resposta, aguardaremos que o participante nos envie a resposta HTTP 2xx para concluir a notificação e finalizar as tentativas.
Em caso de outras respostas que não sejam HTTP 2xx, haverá retentativas da notificação.
Endpoint para receber Webhook de Restituição do Pagamento Finalizada
Notificação de validação de recebimento
Esta notificação ocorrerá quando um recebimento for enviado ao participante indireto por meio do canal primário de tráfego de mensagens do Banco Central. O Banco BS2 enviará a notificação e aguardará a resposta em tempo hábil para efetivar a transação dentro do SLA acordado.
Para esta notificação enviamos o contrato a seguir:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| data | Data em que o Banco Central enviou a solicitação de recebimento para o Banco BS2 | date-time | Não |
| endToEndId | Identificador da transação | string | Sim |
| transactionId | Identificador único do recebimento gerado pelo BS2 | string | Sim |
| CampoLivre | Mensagem informada pelo pagador | string | Sim |
| cnpjIniciadorPagamento | CNPJ da instituição iniciadora do pagamento, utilizado no OpenBanking | string | Sim |
| status | Status do pagamento, conforme tabela Status do Pagamento | string | Não |
| tipoIniciacao | Tipo de iniciação utilizado no recebimento, conforme tabela Tipo de iniciação | string | Não |
| finalidade | Finalidade da transação, conforme tabela Finalidade da transação | string | Não |
| valor | Valor do recebimento | double | Não |
| recebedor | Dados do recebedor (banco, agência, conta, documento, etc.) | object | Não |
| pagador | Dados do pagador (banco, agência, conta, documento, etc.) | object | Não |
| chaveDict | Chave Pix utilizada no recebimento da transação Pix | string | Sim |
| prioridadeTransacao | Prioridade da transação, conforme tabela Prioridade Transação | string | Não |
| tipoPrioridadeTransacao | Tipo de prioridade da transação, conforme tabela Tipo Prioridade | string | Não |
| valorSaqueOuTroco | Valor do Saque ou troco, utilizado para finalidades de Pix Saque/Troco | double | Sim |
| ispbFacilitadorServicoSaqueOuTroco | ISPB do facilitador do serviço de Saque ou Troco | string | Sim |
| modalidadeAgente | Tipo de modalidade do agente, conforme tabela Modalidade do Agente | string | Não |
Como resposta, aguardaremos que o participante nos envie a resposta HTTP 2xx para concluir a notificação e finalizar as tentativas.
No corpo da resposta, deverá conter o json com os seguintes campos:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| transacaoAutorizada | Identifica se o participante indireto aceita true ou rejeita false a transação | boolean | Não |
| validacoes | Lista com objetos de código de erro e descrição, em caso de rejeição da restituição pelo participante | array of objects | Sim |
Importante:
Caso o participante deseje rejeitar a validação da restituição, então deverá enviar o campo
TransacaoAutorizadaigual afalsee resposta HTTP 2xx.
Em caso de outras respostas que não sejam HTTP 2xx, haverá retentativas da notificação.
Webhook validação Recebimento - Cliente
Notificação de validação de recebimento no canal secundário
Esta notificação ocorrerá quando um recebimento for enviado ao participante por meio do canal secundário de tráfego de mensagens do Banco Central. O Banco BS2 enviará a notificação e aguardará a resposta em tempo hábil para efetivar a transação dentro do SLA acordado.
Nota:
No canal secundário o tempo total para liquidação da transação é de até 45 minutos, sendo que o SPI possuirá 15 minutos para efetuar seu processamento e o recebedor (participante direto e indireto) até 30 minutos.
Para esta notificação enviamos o contrato a seguir:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| data | Data em que o Banco Central enviou a solicitação de recebimento para o Banco BS2 | date-time | Não |
| endToEndId | Identificador da transação | string | Sim |
| transactionId | Identificador único do recebimento gerado pelo BS2 | string | Sim |
| campoLivre | Mensagem informada pelo pagador | string | Sim |
| cnpjIniciadorPagamento | CNPJ da instituição iniciadora do pagamento, utilizado no OpenBanking | string | Sim |
| status | Status do pagamento, conforme tabela Status do Pagamento | string | Não |
| tipoIniciacao | Tipo de iniciação utilizado no recebimento, conforme tabela Tipo de iniciação | string | Não |
| finalidade | Finalidade da transação, conforme tabela Finalidade da transação | string | Não |
| valor | Valor do recebimento | double | Não |
| recebedor | Dados do recebedor do Pix (banco, agência, conta, documento, etc.) | object | Não |
| pagador | Dados do pagador do Pix (banco, agência, conta, documento, etc.) | object | Não |
| chaveDict | Chave Pix utilizada no pagamento da transação Pix | string | Sim |
| prioridadeTransacao | Prioridade da transação, conforme tabelaPrioridade da Transação | string | Não |
| tipoPrioridadeTransacao | Tipo de prioridade da transação, conforme tabela Tipo Prioridade | string | Não |
| valorSaqueOuTroco | Valor do Saque ou troco, utilizado para finalidades de Pix Saque/Troco | double | Sim |
| ispbFacilitadorServicoSaqueOuTroco | ISPB do facilitador do serviço de Saque ou Troco | string | Sim |
| modalidadeAgente | Tipo de modalidade do agente, conforme tabela Modalidade Agente | string | Não |
Como resposta, aguardaremos que o participante nos envie a resposta HTTP 2xx para concluir a notificação e finalizar as tentativas.
No corpo da resposta, deverá conter o json com os seguintes campos:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| transacaoAutorizada | Identifica se o participante aceita true ou rejeita false a transação | boolean | Não |
| validacoes | Lista com objetos de código de erro e descrição, em caso de rejeição da restituição pelo participante | array of objects | Sim |
Importante:
Caso o participante deseje rejeitar a validação da restituição, então deverá enviar o campo
TransacaoAutorizadaigual afalsee resposta HTTP 2xx.
Em caso de outras respostas que não sejam HTTP 2xx, haverá retentativas da notificação.
Webhook validação Recebimento - Cliente
Notificação de validação de restituição
Esta notificação ocorrerá quando uma restituição for enviada ao participante. O Banco BS2 enviará a notificação e aguardará a resposta em tempo hábil para efetivar a transação dentro do SLA acordado.
Para esta notificação enviamos o contrato a seguir:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| returnId | Identificador da transação de restituição | string | Sim |
| endToEndId | Identificador do pagamento que originou a restituição | string | Sim |
| valor | Valor da transação | double | Não |
| solicitadoEmUtc | Data e hora em que o recebimento foi enviado pelo pagador | date-time | Não |
| codigoDevolucao | Código do motivo da devolução que será enviado na PACS004, conforme tabela Motivos de devolução | string | Não |
| tipoDevolucao | Tipo da devolução, conforme tabela Tipo de devolução | string | Não |
| prioridadeTransacao | Prioridade de envio da transação, conforme tabela Prioridade Transação | string | Não |
| motivo | Mensagem destinada ao recebedor | string | Sim |
| ispbPagador | ISPB do banco pagador | string | Sim |
| ispbRecebedor | ISPB do banco recebedor | string | Sim |
Como resposta, aguardaremos que o participante nos envie a resposta HTTP 2xx para concluir a notificação e finalizar as tentativas.
No corpo da resposta, deverá conter o json com os seguintes campos:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| transacaoAutorizada | Identifica se o participante aceita true ou rejeita false a transação | boolean | Não |
| validacoes | Lista com objetos de código de erro e descrição, em caso de rejeição da restituição pelo participante | array of objects | Sim |
Importante:
Caso o participante deseje rejeitar a validação da restituição, então deverá enviar o campo
TransacaoAutorizadaigual afalsee resposta HTTP 2xx.
Em caso de outras respostas que não sejam HTTP 2xx, haverá retentativas da notificação.
Validação Síncrona da(s) Restituição(s) (Pagamento Restituido)
Updated 23 minutes ago