Stripe — Next.js App Router

Complete Stripe integration patterns for Next.js App Router with Server Actions and Route Handlers.

Setup (3 steps)

Step 1: Install

npm install stripe @stripe/stripe-js @stripe/react-stripe-js

Step 2: Environment variables

Copy templates/env-example.txt → .env.local and fill in your keys from Stripe Dashboard.

Env Variable	Value	Exposed to Client
`STRIPE_SECRET_KEY`	`sk_test_...` or `sk_live_...`	NO
`NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`	`pk_test_...` or `pk_live_...`	Yes
`STRIPE_WEBHOOK_SECRET`	`whsec_...`	NO
`NEXT_PUBLIC_APP_URL`	`http://localhost:3000`	Yes

Step 3: Initialize SDK

Copy templates/stripe-server.ts → lib/stripe.ts and templates/stripe-client.ts → lib/stripe-client.ts.

Load references/setup.md for details.

Quick Patterns

Task	Approach	Reference
One-time payment	Checkout Session → redirect to Stripe	`references/checkout.md`
Custom payment UI	Payment Intents + Stripe Elements	`references/payment-intents.md`
Recurring billing	Subscriptions + Invoices	`references/subscriptions.md`
Receive events	Webhook Route Handler	`references/webhooks.md`
Self-service billing	Customer Portal session	`references/customer-portal.md`
Products & pricing	Products + Prices API	`references/products-prices.md`
Marketplace splits	Stripe Connect	`references/connect.md`
Auto tax calc	Stripe Tax	`references/tax.md`
Fraud prevention	Radar rules + 3D Secure	`references/radar-fraud.md`
Usage-based billing	Billing Meter + usage records	`references/billing-meter.md`
Pricing page	Server-fetched prices + checkout button	`references/pricing-page.md`
Stripe ↔ DB sync	Webhook → database update patterns	`references/database-sync.md`
Paywall / auth guard	Middleware + Server Component guards	`references/middleware-guard.md`

Essential Webhook Events

Event	When	Action
`checkout.session.completed`	Payment captured	Fulfill order
`invoice.paid`	Subscription renewed	Extend access
`invoice.payment_failed`	Payment failed	Notify user, retry
`customer.subscription.updated`	Plan changed	Update entitlements
`customer.subscription.deleted`	Cancelled	Revoke access
`payment_intent.succeeded`	Custom flow completed	Confirm order
`charge.dispute.created`	Dispute opened	Alert + evidence

Load references/webhooks.md for handler implementation.

Test Cards

Number	Result
`4242 4242 4242 4242`	Success
`4000 0000 0000 0002`	Generic decline
`4000 0000 0000 9995`	Insufficient funds
`4000 0000 0000 0069`	Expired card
`4000 0025 0000 3155`	3D Secure required
`4000 0000 0000 3220`	3D Secure 2 required

Load references/testing.md for full test cards + Stripe CLI workflow.

Stripe CLI

stripe login
stripe listen --forward-to localhost:3000/api/webhooks/stripe
stripe trigger checkout.session.completed
stripe trigger invoice.payment_failed
stripe logs tail --filter status:400

Templates

Template	Copy To	Description
`templates/stripe-server.ts`	`lib/stripe.ts`	Server-side Stripe instance
`templates/stripe-client.ts`	`lib/stripe-client.ts`	Client-side Stripe.js (lazy)
`templates/webhook-handler.ts`	`app/api/webhooks/stripe/route.ts`	Webhook Route Handler
`templates/checkout-action.ts`	`app/actions/checkout.ts`	Server Action: Checkout Session
`templates/subscription-action.ts`	`app/actions/subscription.ts`	Server Actions: subscription CRUD
`templates/customer-portal-action.ts`	`app/actions/portal.ts`	Server Action: portal session
`templates/env-example.txt`	`.env.local`	Environment variables

Error Handling

Load references/error-handling.md for Stripe error types and retry patterns.

Security

Load references/security.md for PCI compliance, idempotency, and key management.

All References

references/setup.md — SDK init, singleton, TypeScript config
references/checkout.md — Checkout Sessions, hosted vs embedded
references/payment-intents.md — Payment Intents, 3D Secure, capture
references/subscriptions.md — Recurring billing, trials, proration
references/webhooks.md — Signature verification, event routing, idempotency
references/customer-portal.md — Self-service portal setup
references/products-prices.md — Products, Prices, coupons, promo codes
references/connect.md — Marketplace, platform fees, payouts
references/tax.md — Automatic tax calculation
references/radar-fraud.md — Fraud detection, disputes
references/billing-meter.md — Usage-based billing
references/error-handling.md — Error types, retry logic
references/testing.md — Test cards, CLI, test clocks
references/security.md — PCI, keys, idempotency, CSP
references/pricing-page.md — Pricing page component pattern
references/database-sync.md — Stripe ↔ DB sync patterns
references/middleware-guard.md — Auth middleware for paid routes

stripe

Safety Notice

Copy this and send it to your AI assistant to learn