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 tabelaPrioridade 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)


Notificação de recebimento e atualização de Notificação de Infração

Esta notificação será gerada sempre que uma infração for registrada e houver atualização no status das notificações enviadas ou recebidas envolvendo o participante indireto.

Para esta notificação enviamos o contrato a seguir:

Campo

Descrição

Formato

Nullable

id

Identificador da notificação de infração

string

Sim

razao

Motivo da notificação, que pode ser: solicitação de devolução (quando refund_request) ou cancelamento de devolução (quando refund_cancelled)

string

Sim

transacaoId

Identificador da transação que originou a notificação, que pode ser o EndToEndID ou RtrId

string

Sim

causaFraude

Causa da fraude reportada, que pode ser:

  • golpe/estelionato (quando scam)
  • transação não autorizada (quando account_takeover)
  • crime de coerção (quando coercion)
  • acesso e autorização fraudulenta (quando fraudulent_access)
  • outros (quando other)

string

Sim

detalhes

Detalhes informados pela contraparte

string

Sim

status

Status da infração, que pode ser:

  • aberta (OPEN)
  • concluída (CLOSED)
  • cancelada (CANCELLED) ou
  • recebida (ACKNOWLEDGED)

string

Sim

ispbSolicitante

Identificador SPB do participante criador da notificação de infração

string

Sim

ispbContraparte

Identificador SPB do participante contraparte na notificação de infração.

string

Sim

marcadorFraudeId

Id da marcação de fraude, caso a infração tenha sido concluída como aceita (AnalysisResult=AGREED)

string

Sim

resultadoAnalise

Resultado da análise da infração, que pode ser: aceita (AGREED) ou rejeitada (DISAGREE)

string

Sim

detalheAnalise

Detalhes da análise da notificação de infração.

string

Sim

dataCriacao

Data e hora da criação da notificação de infração

date-time

Sim

dataUltimaModificacao

Data e hora da última atualização de status

date-time

Sim

Endpoint para receber Webhook de atualizações na notificação de infração


Notificação de recebimento e atualização de reivindicação de chaves

Esta notificação será gerada sempre que uma solicitação de reivindicação de chaves for registrada e houver atualização no status de portabilidades enviadas ou recebidas envolvendo o participante indireto.

Para esta notificação enviamos o contrato a seguir:

Campo

Descrição

Formato

Nullable

id

Identificador da notificação de infração

string

Sim

tipo

Identifica o tipo de reivindicação, que pode ser: posse (OWNERSHIP) ou portabilidade (PORTABILITY)

string

Sim

tipoChave

Tipo da chave envolvida na disputa de reivindicação. Enum: CPF, CNPJ, PHONE, EMAIL ou EVP

string

Sim

status

Status da reinvindicação, que pode ser:

  • aberta (OPEN)
  • aguardando resolução (WAITING_RESOLUTION)
  • confirmado (CONFIRMED)
  • cancelada (CANCELLED) ou
  • completo (COMPLETED)

string

Sim

ispbDoador

ISPB do banco doador da chave

string

Sim

chave

Chave envolvida na disputa de reivindicação

string

Sim

contaSolicitante

Objeto contendo os dados bancários vinculada à chave envolvida na disputa de reivindicação

objeto

Sim

solicitante

Objeto contendo nome e documento do reivindicador

objeto

Sim

abertoEmUtc

Data e hora da abertura da reivindicação de chave

Sim

aguardandoResolucaoEmUtc

Data e hora da atualização de status para "Aguardando Resolução"

string

Sim

confirmadaEmUtc

Data e hora da atualização de status para "Confirmada"

date-time

Sim

canceladaEmUtc

Data e hora da atualização de status para "Cancelada"

date-time

Sim

completaEmUtc

Data e hora da atualização de status para "Completa"

date-time

Sim

fimPeriodoResolucao

Data e hora quando termina o período de resolução

date-time

Sim

fimPeriodoEncerramento

Data e hora quando termina o período de encerramento. Apenas para reivindicação de posse

date-time

Sim

ultimaModificacao

Data e hora da última modificação do status da reivindicação

date-time

Sim

motivoSolicitacao

Razão informada na confirmação da reivindicação, que pode ser: solicitação do usuário (USER_REQUESTED), conta encerrada (ACCOUNT_CLOSURE), fraude (FRAUD),operação padrão (DEFAULT_OPERATION) ou reconciliação (RECONCILIATION)

string

Sim

motivoCancelamento

Razão informada no cancelamento da reivindicação, que pode ser: solicitação do usuário (USER_REQUESTED), conta encerrada (ACCOUNT_CLOSURE), fraude (FRAUD), operação padrão (DEFAULT_OPERATION), reconciliação (RECONCILIATION)

string

Sim

canceladoPor

Participante que realizou o cancelamento (caso tenha sido cancelada). Enum: doador (DONOR) ou reivindicador (CLAIMER)

string

Sim

participanteIndiretoReivindicador

Identifica se o participante indireto é o reivindicador

boolean

Sim

participanteIndiretoDoador

Identifica se o participante indireto é o doador

boolean

Sim

Endpoint para receber Webhook de atualizações na reivindicação de chave


Notificação de sincronismo de chaves

Esta notificação será gerada sempre que for necessário ajustar as chaves do participante indireto em razão do processo de sincronização de chaves.

Para esta notificação enviamos o contrato a seguir:

CampoDescriçãoFormatoNullable
chaveValor da chave corrigidastringSim
tipoAcaoinformar a ação realizada na chave, que pode ser: VINCULO_REMOVIDO ou VINCULO_CADASTRADOstringSim

Endpoint para receber Webhook de atualizações no sincronismo de chave



Notificação de recebimento e atualização de solicitação de devolução (MED)

Esta notificação será gerada sempre que houver atualização no status de solicitações de devoluções (no âmbito do MED) enviadas ou recebidas envolvendo o participante indireto.

Para esta notificação enviamos o contrato a seguir:

Campo

Descrição

Formato

Nullable

id

Identificador da solicitação

string

Sim

razao

Razão da solicitação de devolução, que pode ser:fraude (FRAUD), falha operacional (OPERATIONAL_FLAW), cancelamento de devolução (REFUND_CANCELLED) ou pix automático (PIX_AUTOMATICO)

string

Sim

valor

Valor solicitado para devolução

double

Sim

comentario

Breve descrição do motivo da solicitação de devolução

string

Sim

status

Status da solicitação de devolução, que podem ser: aberto OPEN), concluído (CLOSED) ou cancelado CANCELLED

string

Sim

ispbSolicitante

Identificador SPB do participante solicitante da devolução

string

Sim

ispbContestado

Identificador SPB do participante sendo contestado

string

Sim

criadoEm

Data e hora da criação da requisição de devolução

date-time

Sim

modificadoEm

Data e hora da última atualização de status

date-time

Sim

idInfracao

Identificador da notificação de infração no caso de devolução por fraude

string

Sim

resultadoAnalise

Resultado da análise, que podem ser: totalmente aceito TOTALLY_ACCEPTED), parcialmente aceito (PARTIALLY_ACCEPTED) ou rejeitado (REJECTED)

string

Sim

detalhesAnalise

Detalhes da análise da requisição de devolução indicando a motivação do resultado

string

Sim

razaoRejeicao

Motivo de rejeição, que podem ser: falta de saldo (no_balance),

conta encerrada (Account_closure) ou outro (Other)

string

Sim

idTransacao

Identificador da transação que originou a solicitação, que pode ser o EndToEndID ou RtrId

string

Sim

idTransacaoDevolucao

Identificador da transação de devolução (completa ou parcial)

string

Sim

Endpoint para receber Webhook de atualizações na solicitacao de devolução (MED)