What Is Idempotency and How Do You Prevent Duplicate Payments?

An operation is idempotent when performing it more than once has the same effect as performing it once. In payments, idempotency is what stops a network timeout, a double-clicked button or an automated retry from debiting a customer twice or paying a beneficiary twice.

Duplicates are one of the most damaging operational failures in payments: they create refund work, disputes, complaints and reconciliation breaks. The defences are simple in principle and worth building properly.

Where do duplicate payments come from?

• Timeouts and retries: your system submits a collection, the response times out, and a retry submits it again. The first request may have succeeded even though you never saw the response.
• User behaviour: a customer clicks pay twice, or an operator resubmits a batch that already went through.
• Duplicate webhook processing: the same status event is delivered more than once and your handler acts on it twice.
• File resubmission: a batch file is uploaded twice, or a corrected file overlaps with the original.

Notice the common thread: the retry itself is usually correct behaviour. The problem is retrying without a way for the receiving system to recognise the repeat.

How do idempotency keys work?

An idempotency key is a unique value your system generates for each logical operation and sends with the request. The provider stores the key with the outcome of the first attempt:

1. You generate a unique key for the instruction, for example when the collection is created in your system.
2. You send the key with the API request.
3. If the request is retried with the same key, the provider returns the original result instead of processing it again.
4. A genuinely new operation gets a new key.

The key must be tied to the business operation, not the HTTP attempt. Generating a fresh key on every retry defeats the purpose entirely.

Why do unique client references matter?

Even where a formal idempotency key is not part of the interface, a unique client reference per instruction achieves much of the same protection:

• Banks and providers can reject or flag instructions that reuse a reference.
• Duplicate collections in a batch file can be detected before processing.
• Reconciliation can match every response, unpaid and settlement entry back to exactly one instruction, as covered in payment statuses and references.

Rules of thumb:

• Generate one reference per payment instruction and never reuse it, even for a resubmission of a failed collection: a resubmission is a new instruction referencing the old one.
• Persist the reference before submitting, so a crash between submission and confirmation still leaves you able to query the outcome.

How do you de-duplicate inbound events?

Idempotency applies to what you receive as well as what you send. Webhooks and callbacks are delivered at-least-once, so:

• Record the message ID of every processed event and skip repeats.
• Make status updates idempotent: setting a payment to successful twice should be harmless.
• Apply state-transition rules so a replayed older event cannot overwrite a newer status.

What about batch files?

For batch file integrations, duplicate protection works at two levels:

• File level: unique file names or sequence numbers, so the bank can reject a file it has already received. Verify acknowledgement files before assuming a submission needs to be resent.
• Record level: unique instruction references within and across files, so an overlapping resubmission cannot debit the same customer twice.

A practical checklist

• One unique reference or idempotency key per logical payment operation, generated and persisted before submission.
• Retries always reuse the original key or reference.
• Never resubmit on timeout without first querying the status of the original attempt, as discussed in retries and stuck payments.
• De-duplicate inbound events by message ID.
• Alert on duplicate references detected anywhere in the pipeline.

Back to the Payment Operations hub.