↔️Entendendo o fluxo das notificações

Entendendo o fluxo das notificações (callbacks) da API 4P Finance.

Esta página tem como objetivo apresentar as notificações ( webhook ). Este recurso está disponível na API de sua conta 4P Finance e permite visualizar os POSTs que a 4P Finance dispara para a URL de retorno definida pelo integrador. Este POST contém apenas uma informação: um token de notificação.

Outras informações sobre o processo de definição da URL de notificação e a mecânica envolvendo a consulta de detalhes de uma notificação podem ser observadas na página Obtendo dados de notificações.

Conhecendo o fluxo de notificações

Assim que é enviado com Sucesso (200) para sua URL de retorno, não significa, por si só, que o fluxo ocorreu completamente. Quando você receber o POST, precisará consultar as informações dessa notificação.

Atenção! O POST que a 4P Finance envia para a sua URL de retorno não contém os dados da transação, mas apenas o token de notificação. Todas as informações sobre a referida transação serão retornadas assim que você consumir o endpoint GET /notification/:token.

O processo de notificação funciona como uma "via de mão dupla", ou seja, será realizada uma requisição POST para a sua URL de retorno após confirmado o pagamento do PIX, em seguida, o seu sistema, em posse do token de notificação, envia uma requisição de consumo ao endpoint GET /pix/notification/:token, em que :token é o token de notificação contido no POST enviado.

O fluxo é determinado pela seguinte ordem:

1. A 4P Finance enviará uma requisição HTTP POST para a URL de callback (webhook) informada no momento da criação da transação.

Essa notificação é disparada automaticamente após:

On-ramp:

1. Após a confirmação do pagamento; e

2. Após a confirmação do envio das criptomoedas na blockchain.

Off-ramp:

1. Após a confirmação do recebimento das criptomoedas.

O POST conterá apenas um token de notificação, permitindo que seu sistema valide e processe o status final da operação de forma segura e automatizada.

Assim que você receber a requisição POST, realize uma requisição GET para a rota /notification/:token, em que :token será o token de notificação que enviamos para você.

Ao realizar novas requisições GET para /notification/:token, você receberá atualizações sobre a transação sempre que houver mudanças, como por exemplo no status: pending, processing, success ou error.

Segurança

Para garantir a segurança da comunicação entre os servidores, é obrigatório que a sua URL de callback (webhook) utilize o protocolo HTTPS.

Recomendamos fortemente que o seu sistema:

• Gere um token único por transação no seu backend;

• Inclua esse token como parâmetro na URL de notificação (notification_url) no momento da criação da transação;

• Utilize esse token para validar a autenticidade das notificações recebidas via POST.

Dessa forma, ao receber uma notificação da 4P Finance, seu sistema poderá:

• Confirmar que a requisição foi originada de uma transação válida criada por você;

• Validar o token recebido e garantir que o requisição corresponde exatamente à transação esperada.

Exemplo de URL webhook (notification_url):

https://webhook.minhaempresa.com.br/pix/?custom_id=12345&seu-token=eae1fe563265167f8d88aec8cd4a7609

O token informado na URL do webhook deve ser o mesmo enviado no payload de criação da transação.

Importante! Se o seu sistema consulta o token enviado, consideramos que a notificação foi realizada com sucesso. Caso não consulte, tentaremos novamente por até 05 dias.

Ou seja, se houver uma requisição ao endpoint GET /notification/:token, entenderemos que você recebeu o POST com o token de notificação e que o consultou, recebendo como resposta todos os dados informativos sobre a confirmação da transação.