/api-commerce-stripe

name: api-commerce-stripe
description: Stripe payment processing — Checkout Sessions, Payment Intents, subscriptions, webhooks, Connect, customer management, error handling

Stripe Patterns

> **Quick Guide:** Use the `stripe` npm package for all server-side Stripe operations. Always verify webhook signatures with `constructEvent()` using the raw request body, never the parsed body. Use idempotency keys on all mutating requests. Keep the secret key server-side only. Handle errors with `instanceof Stripe.errors.StripeError`. Amounts are always in the smallest currency unit (e.g., cents for USD).

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST NEVER expose `STRIPE_SECRET_KEY` in client-side code — it stays on the server only)**

**(You MUST verify webhook signatures with `stripe.webhooks.constructEvent()` using the RAW request body — never parsed JSON)**

**(You MUST use idempotency keys on all mutating (POST) requests to prevent duplicate charges)**

**(You MUST handle all Stripe errors with `instanceof Stripe.errors.StripeError` — never swallow payment errors)**

**(You MUST express monetary amounts in the smallest currency unit — cents for USD, not dollars)**

</critical_requirements>

---

**Auto-detection:** Stripe, stripe, stripe.checkout.sessions, stripe.paymentIntents, stripe.customers, stripe.subscriptions, stripe.webhooks, constructEvent, PaymentIntent, CheckoutSession, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, stripe.prices, stripe.products, stripe.refunds, stripe.transfers, stripe.accounts, Stripe.errors, idempotencyKey, payment_intent.succeeded, checkout.session.completed

**When to use:**

• Creating Checkout Sessions for one-time or subscription payments
• Building custom payment flows with Payment Intents
• Handling webhook events for asynchronous payment lifecycle
• Managing customers, payment methods, and subscriptions
• Building marketplace platforms with Stripe Connect
• Processing refunds and handling disputes
• Setting up products and prices for a catalog

**Key patterns covered:**

• Stripe client initialization with TypeScript types
• Checkout Sessions (one-time payments, subscriptions, setup mode)
• Payment Intents (custom flows, confirmation, capture)
• Webhook signature verification and event handling
• Customer creation, update, and payment method attachment
• Subscription lifecycle (create, update, cancel, trials, proration)
• Products and Prices (catalog management)
• Stripe Connect (account creation, transfers, destination charges)
• Error handling with typed Stripe errors
• Idempotency keys for safe retries

**When NOT to use:**

• Client-side Stripe.js or Stripe Elements (use your frontend framework skill)
• Stripe CLI commands or dashboard configuration
• Non-Stripe payment processors (use their dedicated skill)

**Detailed Resources:**

• For decision frameworks and anti-patterns, see [reference.md](reference.md)

**Core Setup & Payments:**

• [examples/core.md](examples/core.md) — Client setup, Checkout Sessions, Payment Intents, error handling

**Webhooks & Events:**

• [examples/webhooks.md](examples/webhooks.md) — Signature verification, event handling, idempotent processing

**Subscriptions & Billing:**

• [examples/subscriptions.md](examples/subscriptions.md) — Subscription lifecycle, trials, proration, metered billing

**Connect & Platforms:**

• [examples/connect.md](examples/connect.md) — Connected accounts, transfers, destination charges, platform fees

---

<philosophy>

Philosophy

Stripe is a payment infrastructure platform. The `stripe` npm package is the server-side SDK for interacting with the Stripe API. All payment processing happens server-side for security.

**Core principles:**

1. **Server-side only** — The secret key and all payment-creating operations must never run in the browser. Client-side uses Stripe.js (a separate concern) only for collecting payment details. 2. **Amounts in smallest unit** — All monetary values are integers in the smallest currency unit (cents for USD, pence for GBP). `1000` means $10.00, not $1000. 3. **Idempotency for safety** — Every mutating request should include an idempotency key to prevent duplicate charges on network retries. Stripe's SDK auto-generates keys for retries, but you should provide explicit keys for application-level retries. 4. **Webhooks are the source of truth** — Payment status should be confirmed via webhooks, not by polling. Webhook events are the only reliable indicator that a payment succeeded, failed, or requires action. 5. **Error as typed exceptions** — Stripe errors are thrown (not returned as values). Catch with `instanceof Stripe.errors.StripeError` and handle by type for appropriate user responses. 6. **API versioning matters** — Pin your API version. Types reflect the latest API version. Use `apiVersion` in the constructor to lock behavior.

**When to use Stripe:**

• Accepting payments (one-time, recurring, marketplace splits)
• Building subscription billing systems
• Platform/marketplace payment splitting with Connect
• Saving payment methods for future charges

**When NOT to use:**

• Client-side payment form rendering (Stripe.js / Elements is a separate domain)
• Payment processing without a server (Stripe requires server-side secret key)
• Simple donation buttons (Stripe Payment Links may suffice without code)

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Stripe Client Initialization

Create a singleton Stripe client. Secret key from env, API version pinned. See [examples/core.md](examples/core.md) for full setup.

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2026-02-25.clover",
});

Never hardcode the secret key or omit `apiVersion` (behavior changes silently on Stripe API upgrades).

---

Pattern 2: Checkout Sessions

Use `mode: "payment"` for one-time, `mode: "subscription"` for recurring. Stripe hosts the payment page. Always include `{CHEC