What is an idempotency key?
It is how a payment survives a dropped connection without charging the customer twice.
Idempotency key
idempotency tokenclient token
An idempotency key is a unique value a client sends with a request so the server performs the work only once, however many times that request arrives. The server stores the key with the first result and replays that stored result for any repeat.
Your client generates the key, not the server. That is the whole point. If the server made it, a retry would arrive with a fresh key and look like new work.
A UUID per user action is the usual choice. The client creates it once, keeps it for the life of that action, and sends it on the first attempt and every retry after.
Why payments need one
A customer taps Pay. The charge succeeds. Then a mobile network drops the response before it arrives. Your app has no way to tell that apart from a charge that failed, so it retries.
Without a key, that retry is a second charge. With one, the payment provider recognises the key, skips the work, and hands back the original result. The customer is charged once.
This applies to anything you cannot safely repeat. Creating a refund, sending a payout, issuing an invoice. Reads are already safe to repeat, so they need no key.
- GenerateClient mints a UUID for this action.
- SendFirst attempt carries the key.
- StoreServer saves key with the result.
- RetryNetwork drops. Same key returns.
- ReplayStored result, no second charge.
Keep the key but change the request, and the replay is wrong rather than merely repeated. That is the failure this diagram cannot draw.
Idempotency against the things it is mistaken for
| Criterion | What people reach for | What an idempotency key does |
|---|---|---|
| Unique constraint | Blocks the duplicate row, then errors. The caller still does not know if the first attempt worked. | Returns the original result, so the client carries on as if the network never failed. |
| Deduplication job | Finds two charges that already exist and reverses one. That is a refund and an unhappy customer. | The second charge never happens. |
| Retry with backoff | Controls when you retry. Says nothing about what the server does with it. | Makes the retry safe to send at all. |
| Request ID for logging | Traces a call after the fact. | Changes what the server does with a repeat. |
Common questions
01How long should the server keep an idempotency key?
Keep it at least as long as your clients might retry, which in practice means 24 hours or more. Stripe prunes keys once they are at least 24 hours old, and a key reused after pruning starts a new request. Treat 24 hours as the floor you can rely on, not a guaranteed window. Pick a retention period longer than your longest retry schedule, then expire keys so the store does not grow without limit.
02What is the difference between idempotency and deduplication?
Idempotency is a guarantee the server makes about repeated requests, while deduplication is a cleanup step that removes copies after the fact. An idempotency key prevents the second charge from ever happening. Deduplication finds two charges that already exist and tries to reverse one, which means a refund and an unhappy customer.
03Does a database unique constraint do the same job?
A unique constraint stops a duplicate row, but it does not give the caller the original result. The retry gets an error instead of the answer it needed, and your code still has to work out whether the first attempt succeeded. An idempotency key returns the stored response, so the client can carry on as if the network never failed.
04Do GET requests need an idempotency key?
No. GET and DELETE are already idempotent by definition, so repeating them changes nothing beyond the extra call. Stripe says not to send keys on either. Keys belong on requests that create state, such as POST.
