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)
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:
| string | Sim |
| detalhes | Detalhes informados pela contraparte | string | Sim |
| status | Status da infração, que pode ser:
| 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:
| 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:
| Campo | Descrição | Formato | Nullable |
|---|---|---|---|
| chave | Valor da chave corrigida | string | Sim |
| tipoAcao | informar a ação realizada na chave, que pode ser: VINCULO_REMOVIDO ou VINCULO_CADASTRADO | string | Sim |
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)