# What is idempotency in payment processing?

In payment processing, idempotency means that repeating the same request, for example after a timeout, has the same effect as sending it once, so a retry cannot create a second payment. Systems usually achieve this with a unique key the server stores with the first outcome.

- Source: https://finray.tech/intelligence/glossary/idempotency-in-payments/
- Published: 2026-11-21
- Updated: 2026-11-21
- Publisher: Finray Technologies Ltd, Cyprus Companies Registry HE 445903

---

## What does idempotency mean in payment processing?

Idempotency means that sending the same request more than once has the same effect as sending it once. In payments it is the property that protects against double charges and double postings when a request is retried. RFC 9110 defines an idempotent HTTP method as one where the intended effect of several identical requests equals that of a single request.

Networks fail in the middle. A client sends a payment instruction, the connection drops, and no response arrives. The payment may or may not have been made. Without idempotency the client has two bad options: resend and risk paying twice, or not resend and risk not paying at all.

## Why do payment retries need special handling?

RFC 9110 classes PUT, DELETE and the safe methods as idempotent and POST as not idempotent; PATCH, defined separately in RFC 5789, is not idempotent either. Payment creation is almost always a POST. It also advises that clients should not automatically retry a non-idempotent request unless they know it is in fact idempotent or can confirm the original was never applied.

Retries come from many places, not only from a nervous user: client libraries with automatic retry, gateways, message queues that deliver at least once, job runners that restart after a crash, and, increasingly, software agents that repeat a step when an answer is slow. Each of these can send the same command twice.

## How does an idempotency key work?

The client generates a unique key for each logical operation and sends it with the request. The server stores the key together with the outcome. If the same key arrives again, the server returns the stored outcome instead of executing again.

The IETF Idempotency-Key draft (an Internet-Draft in the HTTP API working group, draft 08 at the time of writing, not an RFC) describes the pattern for POST and PATCH. Among its points:

- The key is unique and must not be reused with a different request payload; the draft recommends a UUID or similar random value.
- A repeat of a completed request should get a response consistent with the request having been completed once, as the user intended.
- The same key with a different payload should be answered with 422.
- A retry that arrives while the original is still in progress should get 409.
- A server may require keys on certain operations and answer 400 if one is missing, and may expire keys, in which case it should publish its expiry policy.
- Keys should be validated, and the lookup should include client-specific attributes, so that a guessable key cannot expose another client's stored result.

Stripe's public documentation shows one production implementation. Keys can be up to 255 characters; for its API v1 the first result, including server errors, is saved once the endpoint starts executing and returned for retries; keys may be removed after at least 24 hours; and parameters are compared with the original request, with an error if they differ. Detail differs between providers, so integrators should read each provider's rules.

## What is a worked example?

Illustrative example with synthetic numbers. A client submits a transfer of EUR 1,250.00 with key `k-7f3a`. The server begins processing, books the transfer, and the connection drops before the response is sent.

| Step | Request | Server action | Result |
|---|---|---|---|
| 1 | POST transfer EUR 1,250.00, key k-7f3a | Executes, stores outcome "booked, id T-501" | Response lost |
| 2 | Retry, same key, same payload | Finds key, returns stored outcome | "booked, id T-501", no second booking |
| 3 | Retry, same key, payload EUR 1,520.00 | Detects payload mismatch | 422 rejected, nothing booked |
| 4 (alternative) | A retry arrives while step 1 is still running | Detects the key is in progress | 409 Conflict; the client retries later |

Without the key, step 2 would have booked a second EUR 1,250.00. The cost of one lost response would have been a duplicate payment that someone has to find and reverse.

## What are the design pitfalls?

- **Check-then-write races:** reading "does this key exist?" and then inserting is not safe under concurrency. The uniqueness must be enforced atomically, for example by a unique constraint in the database, so that only one concurrent request can claim the key.
- **Key and effect in separate transactions:** if the payment commits but the key record does not, or the reverse, retries misbehave. Store the key and the effect in the same transaction, or make the effect itself deterministic from the key.
- **Key scope:** keys should be scoped to the client or account, so two clients cannot collide or read each other's results.
- **Expiry too short:** a key that expires before the client stops retrying turns a retry into a new payment.
- **Weak keys:** low-entropy or guessable keys are a security issue; the draft warns about exposing other clients' cached results.
- **Idempotency only at the edge:** a retried internal message or batch job needs the same protection as an external API call.

## What controls must sit outside the model or the client?

For anything that moves money or books an entry, the guarantee should be provided by the system of record, not by the caller's good behaviour and not by an AI model's judgement. OWASP's guidance on excessive agency says that authorisation should be checked in the downstream system, not left to the LLM, and that high-impact actions should be approved by a human. Applied to retries:

- **Server-side keys:** the payment system enforces uniqueness and returns stored results.
- **Approval stays with people:** a retried request does not turn an unapproved action into an approved one; see [four-eyes principle](/intelligence/glossary/four-eyes-principle/).
- **Limits and permissions:** per-client and per-agent limits apply on every attempt; see [segregation of duties](/intelligence/glossary/segregation-of-duties/).
- **Evidence:** the key, the first attempt, each retry and the outcome are recorded in an append-only log such as a [hash-chained journal](/intelligence/glossary/hash-chained-journal/).
- **Reconciliation:** balances are still compared with bank or counterparty records, because idempotency does not catch every kind of difference.

## What does Finray say about this, today?

This entry explains a general concept in payment processing. It does not describe how any Finray product implements idempotency keys. For Finray's core-banking platform, see [Corebanq](/platforms/corebanq/). Buyers evaluating a platform should ask for the provider's documented retry behaviour, key scope and expiry, and test them against their own failure scenarios. For how we build and review software, see [how we build](/company/how-we-build/).

## Frequently asked questions

### What does idempotent mean for a payment API?

An operation is idempotent if doing it several times leaves the system in the same state as doing it once. For a payment API this means a retried request with the same idempotency key returns the original outcome instead of moving money again.

### Why is POST a problem?

POST is not idempotent under RFC 9110, and PATCH is not idempotent under RFC 5789, so a client that loses the response cannot know whether the server acted, and should not blindly resend. An idempotency key lets the server recognise the retry and respond consistently.

### Is the Idempotency-Key header an Internet standard?

Not yet. As of the version we reviewed (draft 08, October 2026) it is an active Internet-Draft in the IETF HTTP API working group, not an RFC. Implementations, including major payment providers, predate it and differ in details such as key expiry.

### What should happen if the same key is sent with different data?

The IETF Idempotency-Key draft says the server should reject it with a 422 status, because a key must not be reused with a different payload. A server may compare a fingerprint of the payload with the stored one to detect this.

### Does idempotency replace reconciliation?

No. Idempotency stops duplicates created by retries inside one system. Reconciliation against bank or counterparty records still finds differences caused by other things, such as a missed notification or a manual action.

## Sources

- [IETF draft-ietf-httpapi-idempotency-key-header (Idempotency-Key HTTP header field), Internet-Draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)
- [RFC 9110, HTTP Semantics, section 9.2.2 Idempotent Methods](https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods)
- [RFC 5789, PATCH Method for HTTP](https://www.rfc-editor.org/rfc/rfc5789.html)
- [Stripe API documentation, Idempotent requests (one vendor's published implementation)](https://docs.stripe.com/api/idempotent_requests)
- [OWASP Top 10 for LLM Applications 2025, LLM06 Excessive Agency](https://genai.owasp.org/llmrisk/llm062025-excessive-agency/)
