...
A implementação da funcionalidade do Webhook será incluída nas máquinas de estado de Pagamentos, com o objetivo de notificar as alterações dos status dos pagementos.
Máquinas de estados
Arranjo PIXPix - POST /pix/payments
Consentimento - POST /consents
...
A deliberação sobre a obrigatoriedade de implementação do Webhook pelas detentoras se teve através de discursões realizadas no GT Especificação, pelo fato em que as iniciadoras precisam se comunicar com todas as detentoras do ecossistema para realizar a iniciação de pagamentos, enquanto a opcionalidade para iniciadora implementar o Webhook se deve pelo fato em querer melhorar a sua experiência na apresentação das informações ao seu cliente, desse modo os recursos existentes seriam o suficiente para a sua implementação.
Iniciadora - Opcional
Detentora - Obrigatório
...
Os eventos que acionarão notificações via Webhook na máquina de estados do consentimento do pagamento serão os status REJECTED e CONSUMED.
...
Notificação sobre pagamento: Arranjo
...
Pix
POST /payments/[Versão da API]/pix/payments/{paymentId}
Os eventos que acionarão as notificações via Webhook na máquina de estados do pagamento: Arranjo Pix da API de Iniciação de Pagamentos serão: ACSC, RJCT, CANC, PATC, PDNG e SCHD.
...
Cenários de notificações
Cenários que podem ocorrer como resultado da convivência entre as chamadas assíncronas do Webhook e as chamadas síncronas do POST/payments ou POST/consents:
Cenário 1: Notificação de Webhook pode chegar antes da resposta do POST. Neste caso, a iniciadora seria notificada de uma alteração de estado de pagamento ou consentimento, cujo o id ela ainda não conhece;
Cenário 2: Não há qualquer ordem ou vínculo garantido entre notificações de Webhook de máquinas de estados diferentes, por exemplo, consentimento e pagamento.
...
Neste caso, a iniciadora seria notificada de um estado final da máquina de consentimento após a notificação do primeiro estado da máquina de pagamento, por exemplo, CONSUMED da máquina de estados do consentimento depois do PDNG da máquina de estados do pagamento
As iniciadoras e/ou detentoras poderão criar mecanismos para tratar os cenários apresentados. Por exemplo, para o Cenário 1, a iniciadora pode optar por guardar a notificação por alguns segundos na espera da finalização do POST ou pode descartar a mensagem de imediato e utilizar o polling.
Diagramas de Sequência
No diagrama de exemplo abaixo, é possível identificar como será o comportamento da Iniciadora de pagamentos no processo de consulta de um pagamento.
A detentora de contas envia uma notificação à instituição iniciadora de pagamento informando que ocorreu uma mudança significativa da máquina de estados da API e que a mesma deverá consultar o pagamento para obter mais informações.
Consulta de Consentimento
...
Consulta de Pagamento
...
Conteúdo do Payload/ URL
O payload será composto pela informação do timestamp do momento da alteração da situação do pagamento;
...
Detentoras de contas e/ou Transmissora de dados: Precisam construir a URI de notificação da seguinte forma:
Exemplo de URI do consentimento
...
Exemplo de URI do pagamento
...
Quando habilitar a funcionalidade de Webhook para a API de Pagamentos, a iniciadora de pagamentos deverá estar apta a receber notificações nos seguintes endereços:
https://itp.com/kong3/open-banking/webhook/[Versão do Webhook]/payments/[Versão da API]/consents/{consentId}https://itp.com/kong3/open-banking/webhook/[Versão do Webhook]/payments/[Versão da API]/pix/payments/{paymentId}
...
A iniciadora de pagamentos, ao perceber que não está recebendo as notificações oriundas da detentora de contas, poderá utilizar os endpoints de consulta para obter informações sobre o andamento de uma determinada transação do consentimento e/ou pagamento.
Endpoints de Consulta:
Consulta de Consentimento | Consulta de Pagamento |
|---|---|
GET /consents/{consentId} | GET /pix/payments/{paymentId} |
Requisitos Não Funcionais
...