Stripe Payments skill for Codex

Done well means: the server decides the amount, the order is fulfilled exactly once from a verified webhook (never from the success redirect), every Stripe write carries an idempotency key, and the whole flow has been exercised in test mode with the Stripe CLI, including a declined card and a 3D Secure card.

Before writing code

1. Read AGENTS.md, the lockfile and the framework config. Find any existing stripe client, webhook route and order model; extend them instead of adding a second client.
2. Check the pinned API version: apiVersion in the client constructor, or the account default in the Dashboard. Field shapes change between versions; code against the pinned one.
3. Confirm keys come from environment variables (STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, publishable key for the client). Never hard-code or log them.
4. Confirm the user is in test mode (sk_test_...). Anything that touches live keys, issues refunds or changes Dashboard settings needs explicit user confirmation first.

Installing stripe (npm or pip) and running the Stripe CLI need network access; in a Codex sandbox with network off, ask for approval or work against what the project already has.

Choose the integration

Need	Default	Why
Standard checkout, fastest to ship	Checkout Session, hosted page (mode: 'payment')	Stripe handles SCA, wallets, tax, receipts
Checkout inside your page	Checkout Session with ui_mode: 'embedded'	Same server logic, no redirect
Fully custom UI and flow	PaymentIntent + Payment Element	Maximum control, more code to own
Save a card for later off-session charges	SetupIntent, then PaymentIntent with off_session: true	Correct mandate and SCA handling
Subscriptions	Hand off to $stripe-billing	Different lifecycle and events
Marketplace payouts to sellers	Hand off to $stripe-connect	Funds flow and onboarding

Prefer Checkout unless the user has a concrete reason for a custom form. Use dynamic payment methods (configured in the Dashboard) instead of hard-coding payment_method_types.

Workflow

• Create Products and Prices (Dashboard or API); store Price IDs in config, not amounts
• Server endpoint creates the Checkout Session or PaymentIntent from your own cart data
• Client redirects or mounts the Payment Element with the returned secret
• Webhook endpoint verifies the signature on the raw body
• Fulfilment runs from the webhook, keyed on the Stripe object ID, exactly once
• Test with the CLI: success, decline, 3DS, async method, duplicate delivery
• Live-mode checklist reviewed with the user before switching keys

Create a Checkout Session (Node)

import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!); // pin apiVersion if the project does

export async function createCheckout(orderId: string, items: { priceId: string; qty: number }[]) {
  return stripe.checkout.sessions.create(
    {
      mode: "payment",
      line_items: items.map((i) => ({ price: i.priceId, quantity: i.qty })),
      client_reference_id: orderId,          // your order, echoed back in the webhook
      metadata: { orderId },
      success_url: `${process.env.APP_URL}/orders/${orderId}?session_id={CHECKOUT_SESSION_ID}`,
      cancel_url: `${process.env.APP_URL}/cart`,
    },
    { idempotencyKey: `checkout-${orderId}` }, // retries return the same session
  );
}

Never accept a price or amount from the browser. Look the cart up server-side and map it to Price IDs, or compute price_data.unit_amount in the smallest currency unit (cents; JPY has no minor unit).

Payment Element (custom flow)

Server: stripe.paymentIntents.create({ amount, currency, automatic_payment_methods: { enabled: true }, metadata: { orderId } }, { idempotencyKey }) and return only client_secret. Client: elements = stripe.elements({ clientSecret }), mount elements.create('payment'), then stripe.confirmPayment({ elements, confirmParams: { return_url } }). On the return page, read payment_intent from the query string and show status, but still fulfil from the webhook.

Webhooks

The signature is computed over the exact bytes Stripe sent. Any body parser that runs first breaks verification.

// Express: raw body for this route only, mounted before express.json()
app.post("/webhooks/stripe", express.raw({ type: "application/json" }), async (req, res) => {
  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(req.body, req.headers["stripe-signature"]!, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return res.status(400).send("bad signature");
  }
  if (await alreadyProcessed(event.id)) return res.sendStatus(200);

  switch (event.type) {
    case "checkout.session.completed":
    case "checkout.session.async_payment_succeeded": {
      const s = event.data.object as Stripe.Checkout.Session;
      if (s.payment_status === "paid") await fulfil(s.client_reference_id!, s.id);
      break;
    }
    case "checkout.session.async_payment_failed":
      await markFailed((event.data.object as Stripe.Checkout.Session).client_reference_id!);
      break;
    case "payment_intent.succeeded":
      await fulfilFromIntent(event.data.object as Stripe.PaymentIntent);
      break;
  }
  await markProcessed(event.id);
  res.sendStatus(200);
});

• Next.js App Router: read await req.text() and pass the string to constructEvent.
• Python: stripe.Webhook.construct_event(request.get_data(), sig_header, endpoint_secret) (Flask) or await request.body() (FastAPI).
• Return 2xx fast; push slow work (email, PDFs) to a queue. Stripe retries failed deliveries for up to three days in live mode, so handlers must be idempotent.
• Events arrive out of order and can be duplicated. Make fulfil idempotent on the order (UPDATE orders SET status='paid' WHERE id=$1 AND status<>'paid'), not just on event.id.
• Subscribe the endpoint only to the event types you handle.

Local testing with the Stripe CLI

stripe login                                            # opens a browser; needs network
stripe listen --forward-to localhost:3000/webhooks/stripe   # prints a whsec_... secret for local use
stripe trigger checkout.session.completed
stripe trigger payment_intent.payment_failed
stripe events resend evt_123                            # replay one event

The whsec_ from stripe listen differs from the Dashboard endpoint secret. Use it locally only.

Test card	Behaviour
4242 4242 4242 4242	Succeeds
4000 0025 0000 3155	Requires 3D Secure authentication
4000 0000 0000 9995	Declined, insufficient funds
4000 0000 0000 0002	Generic decline

Any future expiry, any CVC, any postcode. Test-mode only; never type real card numbers anywhere.

Refunds and disputes

• stripe.refunds.create({ payment_intent, amount? }, { idempotencyKey }). Refunds move money: confirm the order, amount and reason with the user before running one in live mode.
• Listen to charge.refunded and charge.dispute.created to keep your order state honest.

Gotchas

• Fulfilling on the success_url page: users close tabs, and the URL can be loaded by anyone.
• checkout.session.completed with payment_status: 'unpaid' is normal for bank debits and vouchers; wait for async_payment_succeeded.
• Using JSON.stringify(req.body) for verification: re-serialised JSON never matches.
• Mixing test and live objects: IDs from one mode do not exist in the other.
• Rounding: amounts are integers in minor units. 19.99 * 100 is 1998.9999999999998; use Math.round or integer cents throughout.
• Expanding everything: retrieve with expand: ['line_items'] only where you need it.
• A webhook endpoint secret per endpoint and per mode; rotating it in the Dashboard breaks verification until the env var is updated.

Going live (confirm each item with the user)

• Live keys stored in the secret manager, not in .env committed to git
• Live webhook endpoint created with the same event list; its secret deployed
• Statement descriptor, business details and payment methods set in the Dashboard
• Radar rules reviewed; tax collection decided (Stripe Tax or none)
• One real low-value payment made and refunded by the user, not by the agent

Verification

• stripe listen output shows each event returning [200].
• Run stripe trigger checkout.session.completed twice for the same order (or events resend): the order is fulfilled once.
• A 3DS card completes after the challenge; a decline card leaves the order unpaid with a readable message.
• Unit-test the handler with a payload signed by stripe.webhooks.generateTestHeaderString.

Report template

**Flow:** Checkout Session (hosted), mode=payment, API version pinned to <version>
**Endpoints:** POST /api/checkout, POST /webhooks/stripe (events: checkout.session.*, charge.refunded)
**Idempotency:** session keyed on orderId; fulfilment guarded by orders.status
**Tested (test mode):** 4242 success, 3155 3DS, 9995 decline, duplicate delivery -> single fulfilment
**Not done / needs user:** live webhook endpoint, live keys, Dashboard branding