Idempotency keys: why payment APIs need them and how to use them
A request times out. Did the payment go through? Retry and you might charge the customer twice; do not retry and you might lose the sale. Idempotency keys remove the dilemma.
What is an idempotency key in a payment API?
An idempotency key is a unique value your system sends with a request that creates something — a payment, refund or payout. If the same request is sent again with the same key, the API returns the result of the first request instead of performing the action a second time. That makes it safe to retry after a time-out without risking duplicate charges or payouts.
- An operation is idempotent if doing it twice has the same effect as doing it once.
- Time-outs leave you not knowing whether a request succeeded — retries are only safe with idempotency.
- Generate one key per intended operation, and reuse it for every retry of that operation.
- Never reuse a key for a different payment.
The problem: "did it work?"
Your server asks the payment API to create a payout. The network is slow, and your request times out before the response arrives. There are two possibilities:
- the request never reached the API, so no payout was created; or
- the payout was created, but the response was lost on the way back.
From your side, the two look identical. Retrying fixes the first case and causes a duplicate payout in the second. For money movement, both outcomes — losing the operation or doing it twice — are unacceptable.
How idempotency keys solve it
With an idempotency key, the retry is safe in both cases:
- Before sending the request, your system generates a unique key for this specific operation and stores it alongside your own record (for example, the payout row in your database).
- It sends the request with the key, typically in a request header.
- If the request times out, it retries with the same key.
- If the API already processed that key, it returns the original result instead of creating a second payout. If it never saw the key, it processes the request normally.
POST /payouts
Idempotency-Key: 5f6d2c1e-8b3a-4c2f-9e71-2a0d4b9c7e13
{ "amount": 250000, "beneficiary_id": "ben_123", "reference": "INV-2041" }The header name and format vary by provider — check the API reference for the exact details.
Rules for using idempotency keys
- One key per intended operation. The key represents "this payout for invoice INV-2041", not "a payout".
- Store the key before sending. If your own process crashes mid-request, you can recover the key and retry safely.
- Reuse it for every retry of that operation — and only that operation.
- Keep the request body identical on retries. Many APIs reject a reused key with different parameters, to protect you from mistakes.
- Use unguessable values, such as UUIDs, rather than sequential numbers.
- Back off between retries, and stop after a sensible number of attempts; then check status through the API.
Where you need them
| Request | Idempotency key? |
|---|---|
| Create a payment or order | Yes |
| Create a refund | Yes — a duplicate refund is money lost |
| Create a payout | Yes — the highest-risk case |
| Fetch a payment's status | Not needed — reading is naturally safe to repeat |
Idempotency on your side too
The same idea applies inside your own system. Webhook handlers should be idempotent by event ID (see Webhooks 101), and background jobs that trigger payments should check whether the payment already exists before creating it. Together, these make duplicate money movement structurally impossible rather than merely unlikely.
Frequently asked questions
What does idempotent mean?
An operation is idempotent if performing it more than once has the same effect as performing it once.
When should I generate a new idempotency key?
For each new operation you intend to perform — each new payment, refund or payout. Reuse the same key only when retrying that same operation.
What happens if I reuse a key with a different amount?
Behaviour depends on the provider, but many APIs reject the request because the parameters do not match the original. Never reuse a key for a different operation.
Do I need idempotency keys for GET requests?
Generally no. Reading data, such as fetching a payment's status, does not change anything and is already safe to repeat.
This article is general information to explain concepts and good practice. It is not legal, tax, accounting or financial advice. Last updated 23 Sep 2026. Found something unclear or out of date? Tell us.