~/guides/LEDGER.md

Guides / Build apps

A Stripe checkout Claude wrote can charge twice: the 4 things to ask it for before launch

A retry without an idempotency key can charge a customer twice. The 4 things a Stripe checkout needs, from Stripe's docs, with prompts for Claude.

Claude Code can wire up a Stripe checkout in minutes, and in normal testing it works. The trouble comes on a bad connection: the payment request goes out, the line drops before the answer comes back, your code can't tell whether the card was charged, so it sends the same payment again and Stripe sees two. This is the full version of my LEDGER Reel: I follow one $20 payment through four checkpoints, explain what each one does and what Stripe's own docs say, and give you prompts you can paste into Claude Code so it checks your checkout and adds what's missing.

01The result first: one order, charged once even on a retry

Illustrated card notice: the second charge for order #1042 is struck out and the total is back to -$20.00
An illustration: one order should never show a second charge. With the four things below, a retry still charges once.

What you get here: the 4 things to check before a Stripe checkout goes live, each explained in plain words with its source in Stripe's docs, and 3 prompts to paste into Claude Code (one full audit, one for idempotency keys, one for the webhook). The one that actually stops a double charge is number 2.

  1. The card number goes straight to Stripe, never through your server.
  2. Every request that charges carries an idempotency key, the same one on every retry.
  3. Radar screens the payment for fraud.
  4. A signed webhook confirms the payment, not the success page alone.
Illustrated network log: POST /v1/payment_intents gets no response, the retry has no key, Stripe receives 2 payments
An illustration: when your code retries without a key, Stripe can only treat it as a new payment.

Why would it charge twice? It isn't Stripe's fault and it isn't the bank's. When a request times out, your code can't tell "Stripe never got it" from "Stripe got it, charged the card, and the reply was lost". If it simply sends the same payment request again, Stripe has no way to know it's a retry, so it treats it as a new payment.

021: the card number goes straight to Stripe, not through your server

Audit everything first (the one-prompt version)
Check whether this project's Stripe checkout does these 4 things, add what is missing, and tell me which files you changed:
1. Card numbers are collected only by Stripe Checkout or Elements and never pass through my server.
2. Every request that creates or confirms a charge sends an Idempotency-Key, and retries reuse the same key.
3. Payments are screened by Radar.
4. Payment is confirmed by a webhook with a verified signature, not by the success page alone.
Stripe's security guide with 'directly to Stripe without it passing through your servers' highlighted
From the docs: payment details go directly to Stripe without passing through your servers.

Collect card numbers with Stripe Checkout or Elements. Stripe's Checkout docs list three UIs: Full page (a Stripe-hosted payment page, or one embedded on your site), Embedded form (a form on your site) and Elements (payment components you lay out yourself). In all three, Stripe's own fields collect the card number and send it directly to Stripe. The security guide says it plainly: with these low-risk integrations payment information goes directly to Stripe without passing through your servers, which also reduces your PCI obligations.

  1. Ask Claude: "Which component collects the card number in this project? Does any code ever read a full card number?"
  2. If the answer isn't Checkout or Elements, ask it to switch to one of them.
  3. You can store the card type, last four digits and expiry date that Stripe returns; the docs say these are outside PCI scope.

032: an idempotency key on every payment

Stripe's Idempotent requests docs with 'Retries with the same key return the saved response' highlighted
From the docs: a retry with the same key gets the saved result of the first request.

An idempotency key is a unique ID you send in the Idempotency-Key header of a POST request. Stripe saves the result of the first request made with that key; when the same key comes in again, it returns the saved result instead of doing the work a second time. So a retry after a dropped connection gets the first payment back, not a second charge. Replayed responses carry the header Idempotent-Replayed: true, which you can use to confirm it.

  1. One key per payment: Stripe suggests a UUID v4, or a key derived from your order or cart ID. Keys can be up to 255 characters; don't put emails or other personal data in them.
  2. Send it with every request that creates or confirms a charge (creating or confirming a PaymentIntent, creating a Checkout Session).
  3. Store the key with the order and reuse the same key with the same parameters on every retry. The same key with different parameters returns an error.
  4. Keys can be removed once they are 24 hours old, so only retry with a key inside that window. If the outcome is still unknown after that, don't send it again: look the payment up first (Dashboard, API or webhook events).
  5. A 409 means another request with the same key is still running: wait, then retry with the same key and parameters, not a new key.
Paste into Claude Code: add idempotency keys (replace the [ ] parts)
Audit the Stripe payment code in this project for places that could charge twice:
1. List every request that creates or confirms a charge ([e.g. PaymentIntent create / confirm, Checkout Session create]).
2. Make each one send an Idempotency-Key that is generated once per [order / cart] (UUID v4 or derived from the order ID, no personal data), stored with the order, and reused unchanged, with the same parameters, on every retry.
3. Disable the Pay button after the first click; when the front end retries after a timeout it must reuse the same key, never create a new one.
4. Show me the diff and explain where a retry could still become a second charge.

043: let Radar screen for fraud

Stripe's How Radar works docs with 'Radar screens all payment attempt types' highlighted
From the docs: Radar screens all payment attempt types.

Radar is Stripe's fraud protection. The docs say Radar screens all payment attempt types (successful, declined, blocked and flagged for review) across the payment methods it supports. There are four plans, Lite, Standard, Plus and Pro; the higher ones add custom rules, risk scores, manual reviews and more.

054: confirm payment with a signed webhook, not the success page

Stripe's Fulfill orders docs with 'it's not guaranteed customers visit that page' highlighted
From the docs: you can't rely on the success page alone, because customers aren't guaranteed to see it.

Don't mark an order paid just because the customer reached your success page. Stripe's fulfillment guide is blunt about it: you can't rely on the landing page alone, because it's not guaranteed customers visit it; someone can pay successfully and lose their connection before the page loads. The right way is to let Stripe tell your server directly: when a payment completes it sends a checkout.session.completed event, and every event is signed, with the signature in the Stripe-Signature header.

  1. Create a webhook endpoint under Workbench → Webhooks in the Stripe Dashboard; to test locally, run stripe listen --forward-to localhost:4242/webhook.
  2. Verify every event's signature with Stripe's official library, using the raw request body, the Stripe-Signature header and the signing secret that starts with whsec_. If your framework changes the raw body, verification fails.
  3. Return a 2xx quickly, then do the slower work such as shipping or granting access. In live mode Stripe retries failed deliveries for up to three days.
  4. Make the order-handling function safe to run more than once: the same event can arrive more than once, so record the event IDs you've handled.
  5. The success page can trigger the same function too (Stripe recommends doing both, because webhooks can be a little late), but never rely on it alone.
Paste into Claude Code: add a webhook with signature verification
Add a Stripe webhook to this project:
1. Listen for checkout.session.completed (and checkout.session.async_payment_succeeded if we accept delayed payment methods).
2. Verify the signature with Stripe's official library, using the raw request body, the Stripe-Signature header and the whsec_ secret from an environment variable.
3. Return 200 quickly, then handle the order; the order-handling function must be safe to call many times for the same session (record handled event IDs).
4. Stop marking orders paid from the success page alone.
5. Tell me how to test it locally with stripe listen and stripe trigger.

06Good to know

  1. Everything here comes from Stripe's own docs, which I checked page by page on 9 November 2026, and describes API v1 behaviour. API v2 handles idempotency differently (Stripe says the replay behaviour differs and it uses a 30-day window); if you use v2, read its own overview.
  2. I didn't run a real checkout for this Reel and nobody was charged. The card notice, the network log and the cubes in the video and in this guide are illustrations; only the doc screens with an address bar are captures of Stripe's docs.
  3. "A retry still charges once" depends on the same key, the same parameters, and the key not having been removed yet. If you still don't know the outcome after 24 hours, find out what happened to that payment before charging again.
  4. Before going live, run through it in a Stripe sandbox with the test card (4242 4242 4242 4242): double-click Pay on purpose, drop the connection on purpose, and check there is exactly one order and one charge.
  5. Never paste a live secret key into a chat or into code; keep it in an environment variable.

Sources

Related guides