nextjs-stripe-integration

name	nextjs-stripe-integration
description	Add Stripe payment processing to Next.js projects. Implement checkout sessions, payment handling, subscriptions, webhooks, and customer management. Use when adding Stripe to a Next.js project, building payment flows, implementing subscriptions, or integrating payment processing.

Next.js + Stripe Integration

This Skill teaches Claude how to implement Stripe payment processing in Next.js projects, including one-time payments, subscriptions, webhooks, and customer management. Based on real-world implementation experience with modern Stripe APIs and authentication frameworks.

⚠️ CRITICAL: Breaking Changes in Modern Stripe.js

stripe.redirectToCheckout() is DEPRECATED and no longer works!

Modern Stripe implementations use the checkout session URL directly:

// ❌ OLD (BROKEN)
const { error } = await stripe.redirectToCheckout({ sessionId });

// ✅ NEW (CORRECT)
const session = await stripe.checkout.sessions.create({...});
window.location.href = session.url; // Use the URL directly!

Quick Start Checklist

When implementing Stripe in a Next.js project:

1. Install dependencies: stripe and @stripe/stripe-js
2. Configure environment: Add NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY and STRIPE_SECRET_KEY to .env.local
3. Access env vars correctly: Load inside functions, NOT at module level (critical for runtime)
4. Create API routes: Build endpoints for checkout sessions, webhooks, and customer portal
5. Build UI: Create checkout forms and payment pages
6. Handle webhooks: Set up secure webhook handlers for payment events
7. Update middleware: Add payment routes to unauthenticatedPaths if using auth middleware
8. Test locally: Use Stripe CLI for webhook testing

Core Implementation Patterns

1. Environment Setup & Runtime Loading

# .env.local
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

CRITICAL: Access environment variables inside API route functions, NOT at module initialization:

// ❌ WRONG - Fails at build/startup
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
export async function POST() { ... }

// ✅ CORRECT - Variables loaded at runtime
export async function POST(request: NextRequest) {
  const stripeSecretKey = process.env.STRIPE_SECRET_KEY;
  if (!stripeSecretKey) {
    return NextResponse.json({ error: 'API key not configured' }, { status: 500 });
  }
  const stripe = new Stripe(stripeSecretKey);
  // ... rest of function
}

Important: Only use NEXT_PUBLIC_ prefix for publishable keys. Secret keys stay server-side only.

2. One-Time Payments (Checkout) - Modern Approach

API Route (app/api/checkout/route.ts):

• Load Stripe with secret key inside the function
• Create a Stripe checkout session with mode: 'payment'
• Return the full session URL (not just session ID)
• Verify webhook signatures on payment success

// ✅ CORRECT: Load env vars inside function
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const session = await stripe.checkout.sessions.create({...});
return NextResponse.json({ url: session.url }); // Return URL directly

Client Side (Simplified):

• NO need to load Stripe.js for basic checkout
• Call checkout API route
• Redirect to session.url directly from response
• Handle success/cancel redirects via query parameters

3. Subscriptions

Differences from one-time payments:

• Create products in Stripe Dashboard with recurring pricing
• Use mode: 'subscription' when creating checkout sessions
• Manage customer subscriptions in database
• Handle multiple lifecycle events via webhooks

Key workflow:

1. Fetch available subscription tiers from Stripe API
2. Display pricing page with subscription options
3. Create checkout session with subscription mode
4. Handle customer.subscription.created webhook
5. Sync subscription status to your database

4. Webhook Handling

Critical security requirements:

• Verify webhook signatures using Stripe's libraries
• Use raw request body for signature validation (disable body parsing)
• Handle these key events:
  • payment_intent.succeeded — one-time payment confirmed
  • customer.subscription.created — new subscription
  • customer.subscription.updated — subscription changes
  • customer.subscription.deleted — cancellation
  • invoice.payment_succeeded — renewal payment

Webhook endpoint (app/api/webhooks/stripe/route.ts):

• Accept POST requests from Stripe
• Verify signature: stripe.webhooks.constructEvent(body, signature, secret)
• Process event and update database
• Return 200 status to acknowledge

5. Authentication Middleware Configuration

When using WorkOS or similar auth frameworks, explicitly allow payment routes:

// middleware.ts
export default authkitMiddleware({
  eagerAuth: true,
  middlewareAuth: {
    enabled: true,
    unauthenticatedPaths: [
      '/',
      '/sign-in',
      '/sign-up',
      '/api/checkout',              // Allow unauthenticated checkout
      '/api/webhooks/stripe',       // Allow webhook delivery
      '/payment-success',
      '/payment-cancel',
    ],
  },
});

Why: Without this, auth middleware intercepts payment routes, causing CORS errors when the frontend tries to call them.

6. Customer Portal

Enable users to manage subscriptions without custom code:

• Configure Customer Portal in Stripe Dashboard
• Create API route that generates portal sessions
• Redirect users to portal for managing subscriptions, payment methods, and invoices

Implementation Guide

Setup Phase

1. Create Next.js project (or use existing)
2. Install Stripe packages:

   npm install stripe @stripe/stripe-js
   

3. Get API keys from Stripe Dashboard → Developers → API Keys
4. Add keys to .env.local
5. Add .env.local to .gitignore

Build Checkout Flow (One-Time Payments)

1. Create app/api/checkout/route.ts:

   • Load Stripe with secret key inside the function
   • Accept POST with amount and metadata
   • Create checkout session
   • Return session.url directly (not just session ID)
   • See API_ROUTES.md for complete code

2. Create checkout page:

   • Simple button component (no Stripe.js needed for basic flow)
   • Call checkout API route on button click
   • Redirect to response.url directly
   • Handle success/cancel via query parameters

3. Create success page:

   • Accepts session_id query parameter
   • Retrieves session details from Stripe (optional - for confirmation display)
   • Displays confirmation message
   • Can fetch order details from your database

Build Subscription Flow

1. Create product in Stripe Dashboard (recurring pricing)

2. Create app/api/subscriptions/list/route.ts:

   • Fetch products and prices from Stripe API
   • Return formatted subscription tiers

3. Create app/api/checkout-subscription/route.ts:

   • Similar to checkout flow but use mode: 'subscription'
   • Link to price ID instead of amount

4. Create subscriptions page:

   • Fetch available tiers from API
   • Display subscription cards with pricing
   • Implement checkout on selection

5. Create app/api/customer-portal/route.ts:

   • Accept POST request
   • Create portal session with customer ID
   • Return portal URL

Webhook Integration

1. Create app/api/webhooks/stripe/route.ts:

   • Disable body parsing: export const config = { api: { bodyParser: false } }
   • Extract raw body and signature from headers
   • Verify: stripe.webhooks.constructEvent(body, signature, webhookSecret)
   • Handle subscription and payment events
   • Update database based on event type

2. Test locally with Stripe CLI:

   stripe listen --forward-to localhost:3000/api/webhooks/stripe
   stripe trigger payment_intent.succeeded
   

3. Deploy webhook endpoint to production

4. Add webhook endpoint URL in Stripe Dashboard → Webhooks

5. Use production secret key for production webhooks

Best Practices

• PCI Compliance: Always load Stripe.js from Stripe's CDN, never bundle it
• Singleton Pattern: Lazy-load Stripe.js only when needed (performance optimization)
• Environment Variables: Use NEXT_PUBLIC_ only for publishable keys
• Error Handling: Catch and log errors from Stripe API calls
• Webhook Security: Always verify signatures; never trust webhook data without verification
• Database Sync: Store customer IDs, subscription status, and invoice data in your database
• Testing: Use Stripe test mode keys during development; switch to live keys only in production
• Customer Portal: Leverage it for subscription management instead of building custom UI

Common Patterns

Check if User has Active Subscription

// Query your database for customer's subscription status
const subscription = await db.subscriptions.findFirst({
  where: { userId, status: 'active' }
});
return subscription !== null;

Handle Failed Payments

Listen for invoice.payment_failed webhook and:

• Send customer notification email
• Update UI to show payment issue
• Offer retry option via customer portal

Prorate Subscription Changes

Stripe handles this automatically when updating subscriptions via the API. Use proration_behavior to control how changes are billed.

Architecture Recommendations

app/
├── api/
│   ├── checkout/route.ts           # One-time payment sessions
│   ├── checkout-subscription/route.ts
│   ├── subscriptions/
│   │   └── list/route.ts           # Get available tiers
│   ├── customer-portal/route.ts    # Manage subscriptions
│   └── webhooks/
│       └── stripe/route.ts         # Webhook handler
├── checkout/
│   └── page.tsx                    # Checkout form
├── success/
│   └── page.tsx                    # Success page
└── subscriptions/
    └── page.tsx                    # Subscription tiers

Deployment Considerations

• Vercel: Natural fit for Next.js projects; environment variables work seamlessly
• Environment Variables: Ensure all keys are added to your hosting platform
• Webhooks: Update webhook endpoint URL in Stripe Dashboard after deployment
• HTTPS: Required for production (Stripe won't send webhooks to non-HTTPS URLs)
• Testing: Create webhook endpoints in both test and production modes

References and Resources

• Vercel Next.js + Stripe Guide
• Stripe Subscriptions with Next.js
• Stripe Official Documentation
• Stripe Sample Applications