Idempotency and Duplicate Prevention

Duplicates happen because payments move across networks where a sender cannot always tell whether the first attempt succeeded. A customer system times out while waiting for an acknowledgement and sends the instruction again, a user double clicks a submit button, or a batch job resends a file after a partial failure. Each of these is normal behaviour in a distributed system, so the payment platform must expect duplicates rather than assume they will never happen. In the worked example, the London corporate system sends the USD 120,000 instruction to Meridian Bank, waits thirty seconds for an acknowledgement, receives nothing because of a network delay, and sends the same instruction again. Without a duplicate control, the bank would process two payments of USD 120,000 for one invoice. An idempotency key is a unique value the sender attaches to an instruction, and the receiving system stores that key with the result of the first processing. When the same key arrives a second time, the system returns the stored result instead of processing the payment again, so the sender gets a successful answer and no second payment is created. The key must be unique per instruction, stable across retries, and stored in a place that survives a system restart, because a key lost in a crash cannot protect anything. In the worked example, the corporate system sends the USD 120,000 instruction with key INV-2026-5521-01, Meridian Bank stores the key with the accepted result, and the retry with the same key receives the same accepted result without a second debit. Testing this control means sending the same key twice and confirming one debit, one payment, and two identical responses. A dedupe window is the period during which the system remembers a key and treats a repeat as a duplicate, and the length of the window is a business decision with real risk. A window that is too short lets a late retry through as a new payment, while a window that is too long stores keys forever and slows the system down. Most banks keep keys for days rather than minutes, covering the life of the payment plus the period in which a retry is plausible. In the worked example, Meridian Bank keeps idempotency keys for seven days, so a retry that arrives the next morning is still recognised as a duplicate. Testing the window means sending a duplicate just inside it and confirming it is blocked, and sending the same instruction after it has expired and confirming the system treats it as new. When the same payment arrives twice despite the controls, operations must decide which copy is the real payment and which copy is the duplicate, and that decision must be recorded. The system marks the second copy as a duplicate, links it to the first payment, and sends the sender the original result so the sender knows the payment is already in progress. The duplicate never reaches the ledger, never reserves funds, and never creates a settlement instruction, so the customer account is debited only once. In the worked example, Harbour Bank receives the USD 120,000 payment twice after the correspondent retry, accepts the first copy, marks the second as a duplicate, and returns the original acceptance for both. Testing this path means checking the duplicate record, confirming one debit, and confirming the sender receives the same result for both attempts.