System Design Simple logoSystem Design Simple Follow on YouTube

Free courseModule 7: Background work

Lesson 43 of 92: Idempotency keys: you pressed Pay twice

Course outline

Idempotency keys: retry a payment without charging twice

Idempotency keys let an API tell a retry from a new payment. In our seeded simulation of 1,000 double-clicked payments, a key cut 2,484 charges to 1,000.

In this lesson you will learn

  • What an idempotency key is and why exponential backoff alone cannot stop a double charge
  • How many charges a double click plus lost replies produced in our seeded simulation, with and without a key
  • What Stripe API v1 saves for a key, when it saves it, and why a saved 500 leaves the outcome unknown
  • Why a key reused after Stripe prunes it can start a second payment, and how to reconcile instead

Builds on Lesson 37: Caching layers 6 min read Next: Polling vs webhooks: how the job tells you it is done

Idempotency keys: retry a payment without charging twice: diagrams from the video

Drafted with AI assistance, then checked and edited by a human engineer · How we write

An idempotency key is a unique value the client sends with a request so the server can tell a retry from a new request. In our seeded in-process simulation of 1,000 double-clicked payments, a plain endpoint made 2,484 charges and an endpoint that honours idempotency keys made 1,000, one per payment.

How do idempotency keys work?

An operation is idempotent when running it twice has the same effect as running it once. Creating a payment is not. Once the amount and other parameters are fixed, the client creates one key per payment operation, usually a V4 UUID, and saves it durably before enabling the Pay button, so both clicks and every retry, even after an app restart, send the same key in an Idempotency-Key header. While Stripe still holds the original request for a key, it compares later parameters against it and rejects a reused key sent with changed parameters. A corrected amount needs a new key, and you should use it only once you know the original did not succeed and is no longer running.

A key dedupes only the requests that carry it. Two tabs, two devices or a fresh checkout session make separate keys, so also give each order one payment under a unique constraint on the order ID. The server keeps one record per key and account: a request fingerprint, a status (pending or done) and, once finished, the response to replay.

Why a double click and a lost reply charge twice

The server charges the card, then the reply is lost on the way back. The client sees a timeout and cannot tell whether money moved. Exponential backoff only decides when the retry arrives, and a server that treats every request as new charges again. A double click does the same thing from the other end, sending two requests for one intent.

Our simulation: 1,000 double-clicked payments

Our lab script labs/sd-43/simulate-double-pay-idempotency-key.mjs is a seeded in-process simulation (seed 4343), with no real money or network. Each of 1,000 payments ($5 to $120) is double-clicked, each reply has a 20% chance of being dropped after the handler finishes, and each click retries a lost reply up to 3 times. Runs A and B send the clicks sequentially; run C tests overlapping requests. Rerun on 2026-11-19:

RunRequestsChargesResult
A. Plain endpoint, every request charges2,4842,4841,000 of 1,000 charged 2x or more, 350 charged 3x or more, $91,313.79 extra
B. Idempotency-Key, saved result for repeats2,4841,000every payment charged exactly once, 1,484 repeats answered from the saved result, $0 extra (5 clicks used up their retries without a reply)

2,000 clicks plus 484 retries make 2,484 requests, so 1,484 are repeats.

What Stripe saves for a key, and when

For API v1, Stripe saves the status code and body of the first request with a key once the endpoint starts running, and later requests with that key get the saved response back, 500 errors included (Stripe API: Idempotent requests, checked 2026-11-19).

Stripe API reference, Idempotent requests: for API v1 Stripe saves the status code and body after endpoint execution begins and retries return the saved response, including 500 errors
Stripe API reference, "Idempotent requests". Captured 2026-11-19. Source: docs.stripe.com.

Validation failures that happen before endpoint execution begins do not save an idempotent result. If a request with the same key is still being processed, Stripe can answer with a 409 conflict, which is not saved as the key's result; Stripe's guidance is to wait and retry with the same key and parameters.

A saved 500 leaves the outcome unknown. Stripe's error handling guide says not to retry it with a new key until you know what happened. This article covers API v1; API v2 replays differently.

Two copies at the same moment: claim the key atomically

Run C sends two copies of each of the 1,000 payments at the same instant, with no lost replies. In real traffic only some requests overlap.

Key storePayments double chargedExtra
Check the key, charge, then save the key1,000 of 1,000$62,115.86
Claim the key atomically before charging0 of 1,000$0

Check-then-save fails because both copies pass the check before either saves. The check and the claim have to be one atomic step, in a key store that whichever server gets the retry can read, even after a server dies at 3am. In PostgreSQL that is a unique constraint plus INSERT ... ON CONFLICT DO NOTHING RETURNING, which returns only rows it actually inserted (PostgreSQL docs).

-- claim-idempotency-key.sql
CREATE TABLE idempotency_keys (
  account_id    text NOT NULL,
  operation     text NOT NULL,
  idem_key      text NOT NULL,
  request_hash  text NOT NULL,
  status        text NOT NULL CHECK (status IN ('pending', 'done')),
  provider_key  text NOT NULL UNIQUE, -- fresh per operation, never shared
  provider_params jsonb NOT NULL, -- the exact request sent, reused on recovery
  provider_id   text,            -- provider object ID, once known
  status_code   int,             -- saved HTTP status, once done
  response      jsonb,           -- saved reply body, once done
  created_at    timestamptz NOT NULL DEFAULT now(),
  first_attempt_at timestamptz,    -- set once, committed before the first provider send
  UNIQUE (account_id, operation, idem_key)
);

PREPARE claim(text, text, text, text, jsonb) AS
INSERT INTO idempotency_keys (account_id, operation, idem_key, request_hash, status, provider_key, provider_params)
VALUES ($1, 'create_payment', $2, $3, 'pending', $4, $5)
ON CONFLICT (account_id, operation, idem_key) DO NOTHING
RETURNING idem_key;

EXECUTE claim('acct_1', 'k-123', 'h1', 'pk-123', '{"amount": 5000, "currency": "usd"}'); -- 1 row
EXECUTE claim('acct_1', 'k-123', 'h1', 'pk-123', '{"amount": 5000, "currency": "usd"}'); -- 0 rows
-- one row back: you own the key; COMMIT before calling the provider
-- no row: SELECT the existing record in a new statement, compare
--   request_hash, replay the saved response if done, 409 if pending

An empty RETURNING needs a separate SELECT. At PostgreSQL's default READ COMMITTED level, ON CONFLICT DO NOTHING can skip the insert because of a row its snapshot cannot see; a new statement gets a fresh snapshot (PostgreSQL: transaction isolation). Keep payment records for as long as any retry or reconciliation can run. If that SELECT finds no row, establish the original outcome with the provider before you claim again. At stricter isolation levels, retry on serialization failures.

Commit the pending claim, with the provider key and the exact provider parameters in provider_params, before the external call. A claim left in an open transaction disappears on a crash or rollback, and another request can claim the key and charge again. Right before the first send, set first_attempt_at once (COALESCE(first_attempt_at, now())) and commit it. A pending row with no first_attempt_at was never sent, so the worker may send it, setting the time first. The lab models the claim in memory and leaves out crashes.

When the process crashes mid-payment

The local claim stops a second caller, yet the process can still die before, during or after the provider call, leaving the row pending. Put your local payment ID in the provider object's metadata, and save the provider's object ID on the row as soon as a response returns it.

A recovery worker picks up pending rows older than a timeout, each under a lease. A lease cannot rule out overlap: a worker can pause past its expiry and resume while another holds the renewed lease. Store a fencing token and make every local update conditional on it, including updates from the original request handler, so a paused handler cannot overwrite a recovery that took over.

The token fences only your database. For a lost or unknown response, the worker resends with the saved provider key and provider_params, but only before a cutoff counted from first_attempt_at and set well inside 24 hours. If a 500 is known or replayed, it reconciles first, because Stripe treats a 500 result as indeterminate. A same-key request that overlaps one still in flight can get a conflict; retry it with the same key and parameters. The worker checks the cutoff immediately before each send, yet a process that pauses after the check can still send late. Ruling that out needs provider-side support or another way to fence the external call.

Past the cutoff, stop resending and reconcile: retrieve the object by its saved ID, check the Dashboard request logs, and match verified webhook events through the metadata. Use a new key only when the original did not succeed and is no longer running.

Why a key reused after Stripe prunes it starts a new payment

For API v1, Stripe keeps a key for at least 24 hours and may prune it after that; a key reused after pruning runs as a new request (Stripe API: Idempotent requests). If the first payment went through, that retry can charge the customer again. Stripe's guide to POST requests says to retry an unknown outcome with the same key and parameters only within 24 hours, then reconcile.

Our take

Any operation where a duplicate does harm needs an explicit deduplication plan. Sometimes a natural unique ID covers it, such as an order number under a unique constraint. For a retried charge, use an idempotency key: one per payment operation, an atomic claim committed with the exact provider parameters, rejected payload changes, and a fenced recovery worker that stops resending before the provider can forget the key.

FAQ

What is an idempotency key in simple terms?

A label for one operation that every retry repeats, so the server can spot the repeat and return the saved result.

Does Stripe return the saved response even if the first request failed?

If endpoint execution began, API v1 saves the response, including a 500. Failures before execution begins are not saved. Treat a saved 500 as an unknown outcome and reconcile before trying a new key.

What happens if I reuse an idempotency key after Stripe prunes it?

It runs as a new request, so if the first payment went through, the retry can create a second one. Past 24 hours, reconcile instead of retrying; if the outcome is still unknown, contact Stripe support before charging again.

This article uses public Stripe and PostgreSQL documentation and our own seeded simulation, whose numbers depend on the settings we chose. It does not describe any company's private systems.

Frequently asked questions

What is an idempotency key in simple terms?

A label for one operation that every retry repeats, so the server can spot the repeat and return the saved result.

Does Stripe return the saved response even if the first request failed?

If endpoint execution began, API v1 saves the response, including a 500. Failures before execution begins are not saved. Treat a saved 500 as an unknown outcome and reconcile before trying a new key.

What happens if I reuse an idempotency key after Stripe prunes it?

It runs as a new request, so if the first payment went through, the retry can create a second one. Past 24 hours, reconcile instead of retrying; if the outcome is still unknown, contact Stripe support before charging again.

Sources

  1. Stripe API reference: Idempotent requestsdocs.stripe.com
  2. Stripe: Low-level error handling (server errors, POST requests)docs.stripe.com
  3. Stripe: API v2 overview, idempotencydocs.stripe.com
  4. PostgreSQL 18: INSERT and ON CONFLICTpostgresql.org
  5. PostgreSQL 18: Transaction isolationpostgresql.org

idempotency keysystem designpaymentsAPIsreliability

System Design Simple logo
System Design Simple

Written by a software engineer and system architect with 10+ years of building production web, payment, ticketing and accounting systems in Japan and Nepal. About us