stripe-developer

Stripe Developer Skill

A comprehensive skill for building payment integrations in Next.js applications with Stripe. Covers five domains: Checkout & Payments, Products & Pricing, Subscriptions & Billing, Webhooks, and Customer Portal.

Architecture

This skill uses progressive disclosure with reference files:

stripe-developer/
├── SKILL.md                          ← You are here (orchestrator)
├── references/
│   ├── checkout.md                   ← Checkout Sessions (hosted + embedded)
│   ├── products-prices.md            ← Products, Prices, and pricing models
│   ├── subscriptions.md              ← Subscriptions, billing lifecycle, metered/tiered
│   ├── webhooks.md                   ← Webhook endpoints, signature verification, event handling
│   ├── customer-portal.md            ← Self-service subscription management
│   └── nextjs-supabase-integration.md ← Cross-stack wiring patterns

Routing

When the user's request arrives, determine which domain(s) it touches, then read the appropriate reference file(s):

Checkout & Payments

If the request involves creating a checkout session, one-time payments, payment pages, redirecting to Stripe, embedded checkout, or the Stripe payment form: → Read references/checkout.md

Products & Pricing

If the request involves creating products, setting prices, pricing tiers, free vs. pro plans, price IDs, or configuring what you sell: → Read references/products-prices.md

Subscriptions & Billing

If the request involves recurring payments, subscription lifecycle (create, upgrade, downgrade, cancel, renew), billing intervals, trial periods, metered billing, or subscription status management: → Read references/subscriptions.md

Webhooks

If the request involves listening for Stripe events, webhook endpoints, signature verification, handling checkout.session.completed, invoice.paid, customer.subscription.updated, or any event-driven payment logic: → Read references/webhooks.md

Customer Portal

If the request involves letting customers manage their own subscriptions, update payment methods, view invoices, cancel subscriptions, or self-service billing: → Read references/customer-portal.md

Cross-Stack Integration (Next.js + Supabase + Vercel)

If the request involves wiring Stripe into a Next.js + Supabase stack, syncing subscription status to the database, gating features behind payment status, deploying with Stripe env vars on Vercel, or building a complete SaaS payment flow: → Read references/nextjs-supabase-integration.md

Multiple Domains

Many requests touch multiple domains. For example, "set up subscriptions with a free and pro tier in my Next.js + Supabase app" requires Products & Pricing + Subscriptions + Webhooks + Cross-Stack Integration. Read all relevant files.

Default Stack

• Framework: Next.js (App Router)
• Server SDK: stripe (Node.js)
• Client SDK: @stripe/stripe-js + @stripe/react-stripe-js
• Database: Supabase (Postgres with RLS)
• Deployment: Vercel
• Language: TypeScript

Key Principles

1. Never expose STRIPE_SECRET_KEY to the client. Use NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY for client-side only. The secret key lives server-side exclusively.
2. Use Server Actions or Route Handlers to create Checkout Sessions — never create them from the client.
3. Always verify webhook signatures using stripe.webhooks.constructEvent(). Never trust unverified webhook payloads.
4. Store subscription status locally in your Supabase database. Don't query the Stripe API on every request — it adds latency and hits rate limits.
5. Use stripe listen --forward-to during local development to test webhooks before deploying.
6. Test mode first, always. Use pk_test_ and sk_test_ keys. Test card: 4242 4242 4242 4242, any future expiry, any CVC.
7. Return 200 quickly from webhook handlers. Do async processing after acknowledging receipt.
8. Use Price IDs, not raw amounts — create Products and Prices in the Stripe Dashboard or API, then reference them by ID.
9. Handle cancel_at_period_end — when a user cancels, Stripe keeps the subscription active until the period ends. Don't immediately revoke access.
10. Idempotency — Stripe can send the same webhook event more than once. Use event.id to deduplicate if needed.

Environment Variables

# .env.local
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...   # Client-safe, exposed to browser
STRIPE_SECRET_KEY=sk_test_...                     # Server-only, never expose
STRIPE_WEBHOOK_SECRET=whsec_...                   # For webhook signature verification

Quick Install

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

Stripe Client Setup Pattern

Server-side (singleton)

// lib/stripe.ts
import 'server-only'
import Stripe from 'stripe'

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)

Client-side (singleton via lazy load)

// lib/stripe-client.ts
import { loadStripe } from '@stripe/stripe-js'

let stripePromise: ReturnType<typeof loadStripe>

export function getStripe() {
  if (!stripePromise) {
    stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!)
  }
  return stripePromise
}

Stripe CLI Quick Reference

# Install
brew install stripe/stripe-cli/stripe

# Login
stripe login

# Listen for webhooks locally (forward to your Next.js app)
stripe listen --forward-to localhost:3000/api/stripe/webhook

# Trigger a test event
stripe trigger checkout.session.completed

# Create test fixtures (products + prices)
stripe fixtures fixtures/stripe-fixtures.json

Test Cards

Scenario	Card Number
Payment succeeds	4242424242424242
Payment requires authentication	4000002500003155
Payment is declined	4000000000009995

Use any future expiry date and any 3-digit CVC.