---
title: "Idempotency Key"
url: "https://mahouse.world/glossary/idempotency-key"
type: "glossary term"
topic: "Payments engineering"
author: "Ihor Vlasov"
reviewed: "2026-09-20"
published: "2026-08-10"
---

# Idempotency Key

An idempotency key is a unique value a client attaches to a payment request so that if the request is sent again — because the network dropped the response, the client timed out, a retry fired — the server recognises it as the same operation and returns the original result instead of performing it twice. It is the mechanism that keeps a slow response from becoming a double charge, and every payments API worth integrating supports it.

**Also known as:** Idempotency, Idempotent request, Duplicate-request protection

## Key facts

- **Used at:** payment creation, refunds, payouts, transfers — any request whose repetition would move money twice; also in webhooks (the receiver deduplicates events by ID) and in batch file submission
- **Binding:** an API design convention rather than a rule — Stripe's `Idempotency-Key` header set the pattern; the schemes' reattempt rules and the merchant's own reconciliation are what a missing key breaks
- **Typical mechanics:** the client generates a UUID per logical operation and sends it in a header; the server stores the key with the result for a window (24 hours is common); a repeat with the same key and the same body returns the stored result; a repeat with the same key and a different body is rejected
- **Typical failure without it:** a checkout that times out at 30 seconds while the acquirer approved at 31, the customer clicks again, and two authorisations stand — a refund, a complaint, sometimes a chargeback
- **Parties:** the merchant's engineers, the PSP or gateway whose API honours the key, the orchestration and retry layers that must propagate it, and the customer who is charged once

## How an idempotency key works in practice

A checkout submits a €80 payment to its PSP with the header `Idempotency-Key: 7f3c…`. The PSP receives it, creates the payment, sends the authorisation, gets an approval — and the response to the checkout is lost in a network blip. The checkout's client library times out and retries with the same key. The PSP looks the key up, finds the completed payment, and returns it: one charge, one approval, the checkout shows success. Without the key the retry would have created a second payment, the customer's statement would show two €80 charges, and the merchant's support team would spend the afternoon on it.

The design decisions are in the key's scope and lifetime. The key should represent the logical operation — this order's payment — not the HTTP request, so that a retry from a different server or after a restart still deduplicates. It should be stored with the request body's fingerprint, so that a key reused with different data is an error rather than a silent replay. And it should expire after a window long enough to cover any plausible retry and short enough not to grow forever. Retry logic and cascading, which resubmit deliberately, must carry a new key for a new attempt and the same key for a repeat of the same attempt — a distinction integrations get wrong.

For a payments company the API's idempotency guarantees are part of the product; for a merchant's engineers, the header is the first thing to check in any integration review.

## Example

A marketplace's payout system sends 40,000 transfers on a Friday. A network incident causes 1,800 requests to time out after the PSP had processed them. The system's retry, written without idempotency keys, resends them; 1,800 sellers are paid twice — €410,000 — and the marketplace spends three weeks recovering it, with 90 sellers disputing the clawback. The rebuilt system generates a key per payout and stores it; the following quarter's incident, with 900 timeouts, produces 900 deduplicated responses and no double payments. The PSP's engineers note that the marketplace was the only client on its platform that year to pay out twice at scale, and that the header had been in the documentation since 2011.

## Common mistakes

- Retrying a timed-out payment request without a key.
- A key per HTTP request rather than per logical operation, so a retry from another process is not deduplicated.
- Reusing a key across different payments and getting a stale result for a new order.
- Deduplicating on the client side only, when the server is the one that moved the money.
- Webhook handlers that process the same event twice because they never checked the event ID.

## Related terms

- [Webhook](https://mahouse.world/glossary/webhook.md)
- [Retry Logic](https://mahouse.world/glossary/retry-logic.md)
- [Payment Gateway](https://mahouse.world/glossary/payment-gateway.md)
- [Reconciliation](https://mahouse.world/glossary/reconciliation.md)
- [API](https://mahouse.world/glossary/api.md)
- [Cascading](https://mahouse.world/glossary/cascading.md)

— Ihor Vlasov, M&A FinTech Expert. Last reviewed 2026-09-20. https://mahouse.world/authors/ihor-vlasov