A maioria dos guias de integração VoP para em «envie um nome e IBAN, leia o resultado». A produção acrescenta dois problemas: as redes falham e os clientes repetem, e mais tarde as finanças perguntam «a que pagamento pertencia esta verificação?». Um só campo — um external id estável por pedido — resolve ambos.
Idempotência nos retries
Se um pedido expirar, o seu cliente pode repeti-lo. Sem uma chave de idempotência, isso é uma segunda verificação — custo extra e registos confusos. Anexar o mesmo external id ao retry permite ao sistema reconhecê-lo como o mesmo pedido lógico, por isso os retries são seguros.
Um id, gerado uma vez
Gere o external id quando cria a intenção de pagamento, não por tentativa HTTP. Assim cada retry da mesma verificação lógica leva o mesmo id.
Reconciliação
O mesmo external id é a sua chave de correlação. Armazene-o no registo do pagamento, envie-o com a verificação, e poderá mais tarde juntar o resultado da verificação ao pagamento exato — essencial para litígios, auditorias e análise.
Construa o trilho de auditoria
- 1 Gere um external id por verificação e persista-o com o seu pagamento.
- 2 Envie-o no pedido; reutilize-o em qualquer retry.
- 3 Registe o id de verificação devolvido, o resultado e o BIC respondente associados a ele.
A API Verification of Payee da RoxPay aceita um external id por pedido e devolve o seu próprio id de verificação com o BIC respondente, por isso a idempotência e a reconciliação resultam de um único padrão limpo.