Um pedido de Verification of Payee normalmente devolve um resultado em tempo real, rápido o suficiente para o mostrar antes de o pagador autorizar uma transferência. Mas a VoP é uma chamada de rede a outro banco, e as redes não são perfeitamente fiáveis. Um PSP respondente pode ser lento, uma ligação pode cair, ou um pedido pode acabar numa fila. Uma integração de nível produtivo precisa de um plano para a resposta que chega alguns segundos — ou alguns minutos — atrasada.
Porque é que uma chamada VoP pode tornar-se assíncrona
O esquema define uma janela de resposta apertada, mas o tráfego real produz na mesma casos-limite que tem de gerir com elegância em vez de os tratar como erros graves:
- O PSP respondente está temporariamente sobrecarregado e responde apenas fora do seu tempo-limite síncrono.
- Uma falha de rede transitória dispara uma nova tentativa que conclui depois de o seu pedido inicial já ter regressado.
- Submete muitas verificações em bloco (por exemplo uma remessa de pagamentos) e recolhe os resultados à medida que regressam.
Desenhar o fluxo de webhook
O padrão mais limpo é dar a cada verificação um identificador estável, devolver um estado «pendente» quando a janela síncrona expira, e deixar um webhook entregar o resultado final.
- 1 Submeta a verificação e guarde o seu request ID associado ao pagamento que está prestes a fazer.
- 2 Se não chegar resposta dentro do seu orçamento síncrono, mostre ao pagador um estado «pendente» em vez de um erro.
- 3 Receba o resultado final (correspondência, parcial, sem correspondência ou não disponível) no endpoint do seu webhook.
- 4 Reconcilie o payload do webhook com o request ID guardado e atualize a decisão de pagamento.
Seguro e idempotente por defeito
Verifique a assinatura de cada webhook antes de confiar nele, e torne o seu handler idempotente: o mesmo resultado pode ser entregue mais do que uma vez. Indexe o seu processamento no request ID para que uma entrega duplicada nunca atue duas vezes sobre um pagamento.
A RoxPay devolve um resultado síncrono sempre que pode e recorre a um webhook assinado quando um PSP respondente é lento, para que o seu checkout permaneça responsivo e os seus registos permaneçam completos.