Gran parte delle guide all'integrazione VoP si ferma a «invia nome e IBAN, leggi l'esito». La produzione aggiunge due problemi: le reti falliscono e i client riprovano, e in seguito la finanza chiede «a quale pagamento apparteneva questa verifica?». Un solo campo — un external id stabile per richiesta — risolve entrambi.
Idempotenza sui retry
Se una richiesta va in timeout, il tuo client potrebbe riprovarla. Senza una chiave di idempotenza, è una seconda verifica — costo extra e log confusi. Allegare lo stesso external id al retry permette al sistema di riconoscerlo come la stessa richiesta logica, così i retry sono sicuri.
Un id, generato una volta
Genera l'external id quando crei l'intento di pagamento, non per ogni tentativo HTTP. Così ogni retry della stessa verifica logica porta lo stesso id.
Riconciliazione
Lo stesso external id è la tua chiave di correlazione. Memorizzalo sul record del pagamento, invialo con la verifica e potrai in seguito unire l'esito della verifica al pagamento esatto — essenziale per contestazioni, audit e analisi.
Costruisci la pista di audit
- 1 Genera un external id per verifica e persistilo con il tuo pagamento.
- 2 Invialo nella richiesta; riutilizzalo su ogni retry.
- 3 Registra il verification id restituito, l'esito e il BIC rispondente associati ad esso.
L'API Verification of Payee di RoxPay accetta un external id per richiesta e restituisce il proprio verification id con il BIC rispondente, così idempotenza e riconciliazione derivano da un unico schema pulito.