An idempotency key is a unique value a client sends with a POST or PATCH so the server can recognize a retry and return the first result instead of running the action again. For payments, it turns a network timeout from a double charge risk into a safe retry.
The problem it solves
A client sends a payment request and the connection drops. Did it succeed? Without a key the client cannot tell, and retrying may charge twice. Not retrying may lose the order. A key gives both sides a shared name for the attempt.
What the IETF draft says
The IETF HTTP API working group has a draft for an Idempotency-Key header field. Its abstract says the header can make non-idempotent methods such as POST or PATCH fault tolerant. The version I read (draft 07) is listed as an expired Internet-Draft, so treat it as guidance, not a standard.
It suggests server behavior along these lines:
- Retry after the original finished: return the earlier result, whether it succeeded or failed.
- Same key, different payload: respond with 422, because a key must not be reused for a different request.
- Same key while the first request is still running: respond with 409.
- Key format: unique and random, such as a UUID.
- Expiry: servers may purge old keys and should publish their policy.
Security points
The draft recommends validating keys against the published format and using a composite cache key, such as the client key combined with client specific attributes, to prevent one client's stored response from leaking to another. That second point is easy to miss. If you key your cache on the header alone, a guessed key could return someone else's payment response.
Other points follow from basic API hygiene:
- Scope keys to the authenticated account.
- Store a hash of the request body next to the key so you can detect mismatches.
- Do not log full responses that contain card or account data.
- Make the key check and the payment write one atomic step, or two parallel requests may both pass.
Client rules
- Generate the key before the first attempt, not on each retry.
- Reuse the same key for the same logical payment, and a new key for a new one.
- Retry with backoff, and stop at a sensible limit.
- Keep the key with the order record for reconciliation.
Quick check
Should a retry with a changed amount reuse the key?
No. A changed payload is a different request. Use a new key, or expect a 422 if the server follows the draft.
Is the Idempotency-Key header a finished standard?
Not as of the version I read. It is an expired IETF draft, so check current status before citing it.
Sources
Last reviewed: 19 October 2026.
