Idempotency

Idempotency is the property of an operation that gives the same result whether it is carried out once or many times. In payment and banking software, an idempotent request to move money charges the customer, creates the transfer or posts the ledger entry exactly once, even if the same request reaches the server two or three times. Payment providers, banks and fintech platforms build it into their application programming interfaces (APIs) so that a network failure never turns into a double charge.

The word comes from mathematics, where a function is idempotent if applying it twice changes nothing more than applying it once: $f(f(x)) = f(x)$. The HTTP standard (RFC 9110) classes methods such as GET, PUT and DELETE as idempotent, but POST, the method most APIs use to create a payment, is not. Payment APIs therefore add an idempotency key to POST requests. Idempotency is closely tied to payment retry logic and is distinct from the reconciliation work that finds duplicates after the fact.

Think of the call button for a lift. Pressing it once calls the lift; pressing it five more times while you wait does not call five more lifts. The button is idempotent: extra presses are harmless. A light switch that toggles on and off is the opposite, because every press changes the result.

Payments need to behave like the lift button. When a phone app loses signal halfway through a payment, it cannot tell whether the bank received the request. The safe thing is to send it again. Idempotency is the promise that sending it again is harmless: the bank recognises the second message as the same payment and simply reports what happened the first time, instead of taking the money twice.

A request can time out after the server has already processed it, a mobile user can tap "Pay" twice, a load balancer can resend traffic, and a message queue that guarantees at-least-once delivery will sometimes deliver the same event twice. In each case the sender knows only that it did not get an answer, not whether the action happened.

Without idempotency, the only safe choices are to give up (and risk a lost payment) or retry (and risk a duplicate). Duplicates are costly: a second card charge produces a chargeback or a manual refund, a second outgoing transfer on an irrevocable rail such as FedNow may never come back, and a duplicated batch file in the Automated Clearing House (ACH) network can debit thousands of accounts twice. Nacha's file format includes a File ID Modifier so that two files created on the same day can be told apart, an early form of the same idea.

Most payment APIs follow the same pattern. Stripe, for example, accepts an Idempotency-Key header on POST requests, and the IETF has an Internet-Draft that would standardise that header for HTTP generally (still a draft as of its October 2026 revision). The sequence is:

1. The client generates a unique key for each intended operation, usually a random version 4 UUID, and stores it with its own record of the payment.
2. The client sends the request with the key in a header.
3. The server looks the key up. If it is new, the server records it as "in progress", carries out the operation and saves the response against the key.
4. If a request with the same key and the same parameters arrives later, the server returns the saved response without doing the work again.
5. If the same key arrives with different parameters, the server rejects it as an error, because the client has misused the key.

A short example: a wallet app sends "transfer $100 to account 789, key a1b2" and the connection drops. The app retries with key a1b2. The server finds that transfer T-555 was already created under that key and returns T-555. The customer's balance falls by $100, not $200. Keys are kept for a limited window; Stripe documents that keys can be pruned once they are at least 24 hours old, after which a reused key is treated as a new request.

An idempotent front door is not enough if the layers behind it are not. Well-built payment platforms apply the same principle at every step:

• The ledger. Each entry carries the external reference that created it, and a unique database constraint stops the same reference posting twice, which protects double-entry accounting integrity and makes ledger sharding safer.
• Event consumers. Services that react to webhooks, such as an instant payment notification (IPN), record which event IDs they have already processed.
• Interbank messages. ISO 20022 messages carry an end-to-end identification, and SWIFT gpi payments carry a unique end-to-end transaction reference (UETR) that banks use to spot duplicates.
• Rail connections. An ACH API, a FedNow API or a stablecoin API needs its own duplicate checks, because each rail settles on its own timetable.

Idempotency handles accidental repeats, not deliberate ones. A customer who genuinely pays the same invoice twice sends two different requests with two different keys, and catching that is a job for duplicate-payment controls and fraud detection. It also does not make a payment reversible; a reversal is a new operation with its own key.

Common implementation errors include generating a fresh key on every retry (which defeats the purpose), storing the key only after the operation finishes (so two simultaneous requests both run), and scoping keys globally rather than per account or merchant. Concurrent requests with the same key need a lock or an atomic "insert if absent" so that only one proceeds. Providers that sit between merchants and several processors, such as a payment orchestration layer or a payment gateway, have to pass keys through consistently, or a retry routed to a second payment processor can still create a duplicate settlement.

• RFC 9110: HTTP Semantics (IETF)
• The Idempotency-Key HTTP Header Field (IETF Internet-Draft)