stripe-consistency

stripe (Node.js) — consistent, modern idioms

The Stripe API is stable and extremely well represented in training data — which is the problem: that data spans a decade of integration styles. Generated code mixes the legacy era (stripe.charges.create with card tokens, Sources, client-side stripe.createToken) with the modern era (PaymentIntents, SetupIntents, Checkout Sessions, webhook-driven fulfillment). This skill pins one canonical style — the current PaymentIntents/Checkout model — plus the handling rules (integer amounts, idempotency, raw-body webhooks) whose violation silently corrupts money.

Canonical idioms — always X, never Y

Always	Never	Why
stripe.paymentIntents.create(...) / Checkout Sessions	stripe.charges.create(...) directly	Charges-first flows predate SCA/3DS; PaymentIntents is the payment primitive and handles authentication state machines.
Payment Element / Checkout on the client	stripe.createToken(card) → server token charge	Tokens/Sources are legacy; raw card data on your server expands PCI scope.
amount: 1999 (integer, smallest unit)	amount: 19.99	Amounts are integers in the smallest currency unit. Float dollars either errors or charges the wrong amount. JPY and other zero-decimal currencies use whole units — no ×100.
{ idempotencyKey } options on every mutating call that may be retried	bare create calls in retry loops / job queues	A network timeout + retry without a key = double charge.
new Stripe(key, { apiVersion: "..." }) (pinned)	omitting apiVersion	Unpinned clients shift behavior when the account default version moves.
stripe.webhooks.constructEvent(rawBody, sig, secret)	trusting req.body JSON as an event	Unverified webhooks let anyone "confirm" payments to your endpoint.
express.raw({ type: "application/json" }) on the webhook route	global express.json() before signature check	Signature is computed over the exact raw bytes; parsed-then-restringified JSON never matches. The #1 webhook failure.
Fulfill from checkout.session.completed / payment_intent.succeeded webhooks	fulfilling on the client success redirect	Redirects can be skipped, replayed, or forged; only the webhook (or a server-side retrieve) proves payment.
Idempotent webhook handlers (dedupe on event.id / your own state)	assuming each event arrives exactly once	Stripe retries; duplicates are guaranteed eventually.
expand: ["customer", "latest_invoice.payment_intent"]	N+1 retrieve calls for nested IDs	One request instead of a chain; nested objects come inline.
for await (const x of stripe.X.list(...)) (auto-pagination)	reading only the first list page	has_more: true ignored = silently missing records.
metadata: { orderId } for reconciliation	parsing descriptions or matching on amounts	Metadata round-trips through webhooks; amounts collide.

House style for a payment + webhook pair:

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, { apiVersion: "2024-06-20" });

const intent = await stripe.paymentIntents.create(
  {
    amount: 1999,                       // $19.99 — integer cents
    currency: "usd",
    customer: customerId,
    automatic_payment_methods: { enabled: true },
    metadata: { orderId: order.id },
  },
  { idempotencyKey: `pi-create-${order.id}` }
);

// Webhook route: raw body, verify, ack fast, process async.
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body, req.headers["stripe-signature"], process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }
  res.sendStatus(200);                  // ack before slow work
  queue.enqueue(event);                 // handler must tolerate duplicates
});

Pitfalls that produce silently wrong results

• Float amounts: Math.round(dollars * 100) at the one conversion boundary, integers everywhere else. 19.99 * 100 === 1998.9999... — truncation undercharges by a cent.
• Zero-decimal currencies: amount: 1000 is ¥1000 for JPY but $10.00 for USD. Multiplying JPY by 100 overcharges 100×. Branch on the currency's decimal class.
• Redirect-based fulfillment: a user who closes the tab after paying never hits your success URL — paid but unfulfilled. A user who bookmarks the success URL replays it.
• Missing idempotency keys in queue/cron retries double-charge; reusing a key with a different payload errors — derive the key from the logical operation, not the timestamp.
• First-page-only pagination in reconciliation scripts silently drops everything past item 10 (default limit). Use auto-pagination or loop on starting_after + has_more.
• Reacting to every event type: handle the few you fulfill from; unknown types get a 2xx and are ignored, otherwise Stripe retries them into your error logs forever.
• Logging full event/charge payloads leaks names, emails, addresses. Log event.id, event.type, and your own metadata keys.
• Treating all errors alike: StripeCardError (decline — show err.code / decline_code to the user, do not retry the same card blindly) vs StripeInvalidRequestError (your bug — fix the code) vs StripeRateLimitError/connection errors (retry with backoff + the same idempotency key).

Version notes

Target the current stripe-node v14+ / current API versions. The key line is the PaymentIntents era (SCA, 2019): everything before it — Charges-as-entrypoint, Tokens, Sources — is legacy and should not appear in new code, though training data is saturated with it. Pin apiVersion in the constructor so the SDK types and the wire behavior agree; test with test-mode keys (sk_test_...) and test clocks for subscription time travel.

Workflow

1. Pick the primitive: Checkout Session for hosted flows, PaymentIntent + Payment Element for embedded, SetupIntent for save-card-now-charge-later. Never Charges/Tokens.
2. Compute amounts as integers in the smallest unit at one boundary; carry the currency.
3. Add an idempotency key to every create/update that any retry path can reach.
4. Wire the webhook route first: raw body, constructEvent, fast 2xx, async + idempotent handlers, fulfillment only from checkout.session.completed / payment_intent.succeeded.
5. Use expand and auto-pagination for reads; put reconciliation keys in metadata.
6. When reviewing existing code, flag any "Never" column pattern above and rewrite it in the canonical form rather than patching around it.

For the fuller migration map (legacy flow → modern flow), expanded webhook and error-handling patterns, and more worked examples, read references/stripe-patterns.md.