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:

CampoDescriçãoFormatoNullable
chaveIdempotenciaCampo 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 retentativastringNão
pagamentoIdIdentificador do pagamento gerado pelo Banco BS2stringNão
EndToEndIdIdentificador único da transaçãostringNão
valorValor da transaçãodoubleNão
statusStatus da transação de pagamento, conforme tabela Status do pagamentostringNão
solicitadoEmUtcData e hora em que o pagamento foi solicitado pelo pagadordate-timeNão
dataContabilData contábil da transaçãodate-timeSim
liquidadoEmUtcData da liquidação da transaçãodate-timeSim
rejeicaoApresenta o código e a descrição da rejeiçãoobjectSim
erroDescricaoApresenta a descrição do errostringSim

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:

CampoDescriçãoFormatoNullable
chaveIdempotenciaCampo 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 retentativastringSim
transactionIdIdentificador da transação da cobrançastringSim
endToEndIdIdentificador único da transaçãostringSim
valorValor da transaçãodoubleNão
statusStatus do recebimento, conforme tabela Status do recebimentostringNão
solicitadoEmUtcData e hora em que o recebimento foi enviado pelo pagadordate-timeSim
dataContabilData da contabilização da transaçãodate-timeSim
liquidadoEmUtcData da liquidação da transação emstringSim
motivoRejeicaoApresenta o código e a descrição da rejeiçãoobjectNão
erroDescricaoApresenta a descrição do erro, se tiver ocorrido erro no recebimentostringSim

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:

CampoDescriçãoFormatoNullable
chaveIdempotenciaCampo 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 retentativastringNão
idExternoIdentificador da transação informado pelo participante ao solicitar a devoluçãostringSim
endToEndIdIdentificador do pagamento que originou a devoluçãostringSim
returnIdIdentificador da transação de devoluçãostringSim
valorValor da transaçãodoubleNão
statusStatus da devolução, conforme tabela Status da devoluçãostringNão
solicitadoEmUtcData e hora em que a devolução foi solicitada pelo recebedordate-timeNão
dataContabilData da contabilização da transaçãodate-timeSim
liquidadoEmUtcData da liquidação da transaçãodate-timeNão
motivoRejeicaoApresenta o código e a descrição da rejeiçãoobjectSim
erroDescricaoApresenta a descrição do errostringSim

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:

CampoDescriçãoFormatoNullable
chaveIdempotenciaCampo 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 retentativastringSim
returnIdIdentificador da transação de restituiçãostringSim
endToEndIdIdentificador do pagamento que originou a restituiçãostringSim
valorValor da transaçãodoubleNão
statusStatus da restituição, conforme tabela Status da devoluçãostringNão
solicitadoEmUtcData e hora em que a restituição foi solicitada pelo recebedordate-timeSim
dataContabilData da contabilização da transaçãodate-timeSim
liquidadoEmUtcData da liquidação da transaçãodate-timeSim
motivoRejeicaoApresenta o código e a descrição da rejeiçãoobjectSim
erroDescricaoApresenta a descrição do errostringSim

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:

CampoDescriçãoFormatoNullable
dataData em que o Banco Central enviou a solicitação de recebimento para o Banco BS2date-timeNão
endToEndIdIdentificador da transaçãostringSim
transactionIdIdentificador único do recebimento gerado pelo BS2stringSim
CampoLivreMensagem informada pelo pagadorstringSim
cnpjIniciadorPagamentoCNPJ da instituição iniciadora do pagamento, utilizado no OpenBankingstringSim
statusStatus do pagamento, conforme tabela Status do PagamentostringNão
tipoIniciacaoTipo de iniciação utilizado no recebimento, conforme tabela Tipo de iniciaçãostringNão
finalidadeFinalidade da transação, conforme tabela Finalidade da transaçãostringNão
valorValor do recebimentodoubleNão
recebedorDados do recebedor (banco, agência, conta, documento, etc.)objectNão
pagadorDados do pagador (banco, agência, conta, documento, etc.)objectNão
chaveDictChave Pix utilizada no recebimento da transação PixstringSim
prioridadeTransacaoPrioridade da transação, conforme tabela Prioridade TransaçãostringNão
tipoPrioridadeTransacaoTipo de prioridade da transação, conforme tabela Tipo PrioridadestringNão
valorSaqueOuTrocoValor do Saque ou troco, utilizado para finalidades de Pix Saque/TrocodoubleSim
ispbFacilitadorServicoSaqueOuTrocoISPB do facilitador do serviço de Saque ou TrocostringSim
modalidadeAgenteTipo de modalidade do agente, conforme tabela Modalidade do AgentestringNã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:

CampoDescriçãoFormatoNullable
transacaoAutorizadaIdentifica se o participante indireto aceita true ou rejeita false a transaçãobooleanNão
validacoesLista com objetos de código de erro e descrição, em caso de rejeição da restituição pelo participantearray of objectsSim

⚠️

Importante:

Caso o participante deseje rejeitar a validação da restituição, então deverá enviar o campo TransacaoAutorizada igual a false e 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:

CampoDescriçãoFormatoNullable
dataData em que o Banco Central enviou a solicitação de recebimento para o Banco BS2date-timeNão
endToEndIdIdentificador da transaçãostringSim
transactionIdIdentificador único do recebimento gerado pelo BS2stringSim
campoLivreMensagem informada pelo pagadorstringSim
cnpjIniciadorPagamentoCNPJ da instituição iniciadora do pagamento, utilizado no OpenBankingstringSim
statusStatus do pagamento, conforme tabela Status do PagamentostringNão
tipoIniciacaoTipo de iniciação utilizado no recebimento, conforme tabela Tipo de iniciaçãostringNão
finalidadeFinalidade da transação, conforme tabela Finalidade da transaçãostringNão
valorValor do recebimentodoubleNão
recebedorDados do recebedor do Pix (banco, agência, conta, documento, etc.)objectNão
pagadorDados do pagador do Pix (banco, agência, conta, documento, etc.)objectNão
chaveDictChave Pix utilizada no pagamento da transação PixstringSim
prioridadeTransacaoPrioridade da transação, conforme tabela Prioridade da TransaçãostringNão
tipoPrioridadeTransacaoTipo de prioridade da transação, conforme tabela Tipo PrioridadestringNão
valorSaqueOuTrocoValor do Saque ou troco, utilizado para finalidades de Pix Saque/TrocodoubleSim
ispbFacilitadorServicoSaqueOuTrocoISPB do facilitador do serviço de Saque ou TrocostringSim
modalidadeAgenteTipo de modalidade do agente, conforme tabela Modalidade AgentestringNã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:

CampoDescriçãoFormatoNullable
transacaoAutorizadaIdentifica se o participante aceita true ou rejeita false a transaçãobooleanNão
validacoesLista com objetos de código de erro e descrição, em caso de rejeição da restituição pelo participantearray of objectsSim

⚠️

Importante:

Caso o participante deseje rejeitar a validação da restituição, então deverá enviar o campo TransacaoAutorizada igual a false e 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:

CampoDescriçãoFormatoNullable
returnIdIdentificador da transação de restituiçãostringSim
endToEndIdIdentificador do pagamento que originou a restituiçãostringSim
valorValor da transaçãodoubleNão
solicitadoEmUtcData e hora em que o recebimento foi enviado pelo pagadordate-timeNão
codigoDevolucaoCódigo do motivo da devolução que será enviado na PACS004, conforme tabela Motivos de devoluçãostringNão
tipoDevolucaoTipo da devolução, conforme tabela Tipo de devoluçãostringNão
prioridadeTransacaoPrioridade de envio da transação, conforme tabela Prioridade TransaçãostringNão
motivoMensagem destinada ao recebedorstringSim
ispbPagadorISPB do banco pagadorstringSim
ispbRecebedorISPB do banco recebedorstringSim

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:

CampoDescriçãoFormatoNullable
transacaoAutorizadaIdentifica se o participante aceita true ou rejeita false a transaçãobooleanNão
validacoesLista com objetos de código de erro e descrição, em caso de rejeição da restituição pelo participantearray of objectsSim

⚠️

Importante:

Caso o participante deseje rejeitar a validação da restituição, então deverá enviar o campo TransacaoAutorizada igual a false e 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)