Next.js + Stripe Integration

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_...