Idempotency is the property of an operation that produces the same result whether it is performed once or many times. In payment APIs it means that when a client resends the same charge request after a timeout or network error, the customer is charged once and the retry returns the original result. APIs achieve this with an idempotency key, a unique value sent with a POST request; the server stores the key with the first outcome and returns that stored response to any repeat. Keys should be generated per business operation, locked against concurrent retries, and backed by deduplicated ledger postings and webhooks. Missing idempotency produces double charges, chargebacks and reconciliation breaks that buyers examine in due diligence.
Why idempotency matters in payments
Networks fail in ambiguous ways. A merchant's server sends a €250 charge request, the processor authorises the card, and the response is lost before it reaches the merchant. The merchant does not know whether the charge happened. Without idempotency, a retry creates a second €250 charge, and the customer disputes the duplicate. With idempotency, the retry returns the original approval and no new charge is made.
At scale the cost is real. A platform making 1 million charge calls a month with a 0.1% timeout rate faces 1,000 ambiguous outcomes. If each were blindly retried and half had in fact succeeded, 500 customers would be double-charged, each a likely refund request or chargeback.
How does idempotency work
HTTP methods such as GET, PUT and DELETE are idempotent by definition; POST, which creates resources such as payments, is not. APIs make POST requests idempotent with an idempotency key: a unique value the client generates and sends in a header with the request. The server stores the key with the outcome of the first request. When the same key arrives again, the server returns the stored response instead of executing the operation again.
Stripe's API is a widely used reference. It accepts keys of up to 255 characters, recommends random V4 UUIDs, and compares the parameters of a repeated request with the original, returning an error if they differ so that a reused key cannot silently apply to a different payment. In its v1 API, keys can be pruned once they are at least 24 hours old, after which the same key creates a new request.
Designing for idempotency
Three rules cover most failures. The key must be generated once per business operation (per order, not per HTTP attempt) and stored before the first call, so a crashed process can retry with the same key. The server must lock on the key, so two concurrent retries cannot both execute. And downstream steps, such as ledger postings and webhooks sent to merchants, need their own deduplication, because an idempotent API call can still trigger a non-idempotent side effect.
Idempotency in due diligence
For a buyer of a payment processor or PSP, duplicate-charge incidents, refund volumes linked to them, and whether every money-moving endpoint enforces idempotency are concrete measures of platform quality. Missing idempotency often shows up as unexplained breaks in daily reconciliation.