A checkout sends POST /payments. Your API charges the card, and the response never reaches the phone. The client retries, and the customer pays twice.
Almost every candidate answers "idempotency key" in the first ten seconds. It's the right start. Then the interviewer asks where the key comes from, and most answers stall.
Here's how I've built it, and how most payment teams do it. It comes down to three lessons:
- A key minted per click isn't the purchase. Key the payment on an order the server created.
- The database decides who pays, not your code. One unique index stops the second tab.
- A retry has to be a replay. Same provider key, same stored amount and card, and the same guard on every email and event.
The basics are in my June post, How to Stop Charging Customers Twice. This post is the senior answer.
1. Key the payment on the order, not on the click
Stripe, Adyen, Square and the IETF draft all recommend a random key per request. That protects one request from network retries. It can't tell that two requests are the same purchase. A reload, a second tab or an app restart mints a new key, and the server sees two unrelated payments. That's how one purchase gets charged twice.
The order id is the one value that stays the same. The server creates the order when checkout starts, before the Pay button renders, and every click calls POST /orders/{id}/payments. Stripe's own guidance points the same way. It pairs one PaymentIntent with one cart and bases the idempotency key on the cart's ID. The amount comes from the order too, so a retry can't change what gets charged.
2. Let the database pick one payment per order
Every payment attempt is a row, with the amount, currency and card copied from the order. One partial unique index allows a single live attempt per order, and the claim is one insert against it:
CREATE UNIQUE INDEX one_live_payment_per_order
ON payments (order_id) WHERE status <> 'declined';
INSERT INTO payments (order_id, amount, currency, payment_method)
VALUES ($1, $2, $3, $4)
ON CONFLICT (order_id) WHERE status <> 'declined' DO NOTHING
RETURNING id, amount, currency, payment_method;
One request gets a row back and charges. Every other request gets zero rows. When two inserts overlap, Postgres makes the second wait until the first transaction ends. You write no lock, and you don't need Redis. A declined attempt drops out of the index, so the customer can try another card on the same order.
The tempting version reads the table first and inserts if it finds nothing. Two tabs both read "no payment", and both charge. With the index, 20 parallel clicks on one order still give one charge.

3. Make every retry a replay
A request that loses the claim never charges. It replays a payment that succeeded, or it gets a 409 and tries again shortly. The request that wins sends the provider the amount and card stored on its row, under a key built from that row's id. Here order is the row the server created, already checked against the signed-in customer, and CLAIM_SQL is the insert above:
export async function payOrder(
db: Pool,
paymentProvider: PaymentProvider,
order: Order,
paymentMethod: string,
): Promise<Reply> {
let { rows: [attempt] } = await db.query(
CLAIM_SQL, [order.id, order.amount, order.currency, paymentMethod],
);
if (!attempt) {
const { rows: [live] } = await db.query(LIVE_SQL, [order.id]);
if (live?.status === "succeeded") {
return { status: 201, body: live.charge };
}
({ rows: [attempt] } = await db.query(TAKEOVER_SQL, [order.id]));
if (!attempt) {
return { status: 409, body: { error: "IN_PROGRESS" } };
}
}
try {
const charge = await paymentProvider.charge({
amount: attempt.amount,
currency: attempt.currency,
paymentMethod: attempt.payment_method,
metadata: { paymentId: String(attempt.id) },
}, { idempotencyKey: `payment/${attempt.id}` });
await db.query(SUCCEED_SQL, [attempt.id, charge]);
return { status: 201, body: charge };
} catch (err) {
if (err instanceof ProviderConflictError) {
return { status: 409, body: { error: "IN_PROGRESS" } };
}
// unknown outcome: leave the row processing
if (!(err instanceof CardDeclinedError)) throw err;
await db.query(DECLINE_SQL, [attempt.id]);
return { status: 402, body: { error: "CARD_DECLINED" } };
}
}
The stored row is what makes a crash safe. Say the provider charges the card and the server dies before it saves the result. The row stays processing, and its locked_until lease runs out after 30 seconds. The next click takes the attempt over with TAKEOVER_SQL, an UPDATE that only matches an expired lease, and calls the provider again. Same key, same amount, same card, so the provider returns the first charge instead of making a second one. Send a different card under that key and Stripe refuses the call. That's why the takeover re-sends the stored card, not the one in the new request.
An error that isn't a decline leaves the row at processing, because nobody knows yet whether the money moved. Treating it as a failure would free the order for a second charge.

Provider keys expire, so keep the guard in your database
Stripe keeps idempotency keys for at least 24 hours, so a takeover only touches attempts younger than 23 hours. Older attempts go to a reconciliation job, and so do attempts where Stripe saved a 500, because Stripe replays that 500 to every retry. The job looks the charge up by the paymentId in its metadata. A charge it can't find goes to a person, never back to the provider.
My own book store taught me the same thing about emails. Resend's send call returns an error instead of throwing, so my Stripe webhook answered 200 and a buyer could pay and get nothing. Returning 500 made Stripe retry, but a retry replays the whole event, every email included. One key per email, built from the checkout session id, means a retry sends only the missing ones. Resend keeps those keys for 24 hours too.
So the guard that lasts is a row in your own database. SUCCEED_SQL marks the payment succeeded and queues the receipt and the payment.succeeded event in an outbox, in one statement. The outbox's primary key is (order_id, kind). If a slow request and its takeover both finish, the second one queues nothing, and the customer gets one receipt. I wrote up that pattern in Saved the Order, Lost the Event.
What the interviewer is listening for
"Idempotency key" names the tool. The senior answer says where the key comes from, which is the order. It says who picks the winner, which is a unique index. And it names the receipt and the event as the other things that have to happen exactly once. Say all of it before the interviewer has to ask.
๐ TL;DR
- A random key per click stops network retries, not a reload or a second tab. Pay against a server-created order id.
- A partial unique index allows one live payment per order. Claim with
INSERT ... ON CONFLICT DO NOTHING, never check-then-insert. - A retry is a replay. It sends the same provider key with the stored amount and card. A lease lets the next click take over after a crash.
- Provider keys can expire after a day. Queue the receipt and the event in the statement that marks the payment paid.


