All articles

How to Design a Payment API That's Safe to Retry (A Senior Interview Answer)

"Add an idempotency key" is where a senior answer starts. The rest is where the key comes from, and what the database refuses.

Petar Ivanov

8 min read

On this page

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:

  1. A key minted per click isn't the purchase. Key the payment on an order the server created.
  2. The database decides who pays, not your code. One unique index stops the second tab.
  3. 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:

SQL
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.

Animated: Tab A and Tab B pay for the same order. Tab A's claim gets 1 row and charges the provider. Tab B's claim gets 0 rows, reads the live payment, and gets a 409 while it's processing; when Tab B retries later, it gets 201 with the same charge. A declined card leaves the index so the next card can pay

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:

TypeScript
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.

Animated: request 1 claims row 41 and the provider charges ch_1, then the process dies before saving the result. The next click asks whether the lease expired. At 5 seconds it hasn't, so the click gets a 409. At 40 seconds it has, so the click takes over row 41, sends the same key and stored card, the provider returns ch_1 with no new charge, and the payment is marked paid with 1 receipt. Taking over with a new key would charge the card twice

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.

Written by

Petar Ivanov

Software engineer, author and speaker. I help JavaScript developers grow from mid-level to senior to architect, with production-grade React, Node.js and AI systems.

Whenever you're ready, here's how I can help you:

  1. 1

    The Conscious React: React architecture, design and clean code. 100+ production tips across 6 chapters, updated for React 19, plus 4 companion repos you can clone and run.

  2. 2

    The Conscious Node: Node.js architecture, design and clean code. 157 production tips across 10 chapters, from module boundaries to the transactional outbox and zero-downtime deploys.

  3. 3

    The JavaScript Architect Bundle: Both Complete Packages in one purchase, with the two books, all 7 React and Node companion repos and the AI rules files.

  4. 4

    Free Resources: Architecture playbooks, cheat sheets and the JavaScript Architect Roadmap. Practical guides for the move to senior.