stripe

# AGENTS.md - using `stripe` (Node SDK v23) in a Next.js App Router app

## Install

```sh
npm install stripe server-only
```

## Env vars

| Var | Where to get it |
|---|---|
| `STRIPE_SECRET_KEY` | Dashboard > Developers > API keys (`sk_test_...` for dev) |
| `STRIPE_WEBHOOK_SECRET` | `stripe listen --forward-to localhost:3000/api/stripe/webhook` prints `whsec_...`; prod: Dashboard > Webhooks |
| `STRIPE_PRICE_ID` | Dashboard > Product catalog > price (`price_...`), recurring for subscriptions |
| `APP_URL` | Your origin, used for success_url and cancel_url |

Commit `.env.example` and add `!.env.example` to `.gitignore` (create-next-app ignores `.env*`).

## The one correct path

1. `src/lib/stripe.ts`: lazy `getStripe()` with `import 'server-only'` (see README).
2. `POST /api/checkout`: `checkout.sessions.create({ mode: 'subscription', line_items: [{ price, quantity: 1 }], client_reference_id, success_url: '...?session_id={CHECKOUT_SESSION_ID}', cancel_url })`, return `session.url`, then redirect on the client.
3. `POST /api/stripe/webhook`: `await req.text()`, then `webhooks.constructEvent(body, sig, secret)`. Return 400 on failure.
4. Handle `checkout.session.completed`, `customer.subscription.updated` and `customer.subscription.deleted`. Webhooks, not the success page, decide paid status.
5. Customer portal: `billingPortal.sessions.create({ customer, return_url })`. Needs a saved `customer` id.

## Mistakes agents make

1. `new Stripe(process.env.STRIPE_SECRET_KEY!)` at module top level. This breaks `next build` without keys. Use the lazy getter.
2. `await req.json()` in the webhook. Signature verification needs the raw text from `req.text()`.
3. Passing removed or renamed v23 params, for example `payment_method_types` on `checkout.sessions.create`. Omit it; Checkout picks methods from Dashboard settings. Check the v23 changelog before using older snippets.
4. Granting access on the success page only. Verify via webhook.
5. Persisting paid status to a local JSON file or in-memory Map. This is lost on serverless hosts. Store `stripe_customer_id` and subscription status on the user row in your database.

Do not set `apiVersion`; the SDK pins one.

## Verify (no keys needed)

```ts
const payload = JSON.stringify({ id: 'evt_test', object: 'event', type: 'checkout.session.completed', data: { object: {} } });
const header = stripe.webhooks.generateTestHeaderString({ payload, secret: 'whsec_test' });
// POST payload with header 'stripe-signature' to /api/stripe/webhook with STRIPE_WEBHOOK_SECRET=whsec_test -> expect 200
// POST with a bad signature -> expect 400
```

Then `npm run build && npm run lint`. For real flows use test keys and card 4242 4242 4242 4242.

## Test without keys

No Stripe account or network needed for these checks:

- Build: `next build` must pass with no env vars. Use a lazy client (see above).
- Webhook signature path:

```ts
import Stripe from 'stripe';
const stripe = new Stripe('sk_test_dummy');
const payload = JSON.stringify({ id: 'evt_1', object: 'event', type: 'checkout.session.completed', data: { object: { client_reference_id: 'user_1', subscription: 'sub_1', customer: 'cus_1' } } });
const signature = stripe.webhooks.generateTestHeaderString({ payload, secret: 'whsec_test' });
// curl -X POST localhost:3000/api/stripe/webhook -H "stripe-signature: $signature" -d "$payload"  -> 200
// same request with a wrong header -> 400
```

- API-shaped responses without an account: run `docker run -p 12111-12112:12111-12112 stripe/stripe-mock` and point the client at it: `new Stripe('sk_test_dummy', { host: 'localhost', port: 12111, protocol: 'http' })`.

A real Checkout redirect needs a test-mode key (`sk_test_...`) from https://dashboard.stripe.com/test/apikeys.

# stripe-node

> Official Stripe Node.js SDK (`npm install stripe`). Server-side only. Use it to create Checkout Sessions, subscriptions, customer portal sessions, and to verify webhooks. Never import it in client components.

## Start here

- [Agent guide](https://github.com/stripe/stripe-node/blob/master/AGENTS.md): env vars, Next.js App Router path, common mistakes
- [README](https://github.com/stripe/stripe-node/blob/master/README.md): install and quickstart

## Jobs

- [Subscriptions with Checkout](https://docs.stripe.com/billing/subscriptions/build-subscriptions.md): monthly and yearly plans
- [Checkout fulfillment](https://docs.stripe.com/checkout/fulfillment.md): webhook-driven fulfillment
- [Customer portal](https://docs.stripe.com/customer-management.md): cancel, switch plan, update card
- [Webhook signatures](https://docs.stripe.com/webhooks/signatures.md): raw body verification
- [Create Checkout Session](https://docs.stripe.com/api/checkout/sessions/create.md): API reference

## Reference

- [Changelog and migration](https://github.com/stripe/stripe-node/blob/master/CHANGELOG.md): breaking changes per major version
- [Testing](https://docs.stripe.com/testing.md): test cards and keyless checks