nextjs-stripe-integration_skill

Overview

This skill adds Stripe payment processing to Next.js projects, covering one-time checkout, subscription flows, webhooks, and customer management. It focuses on modern Stripe patterns, secure webhook handling, and runtime-safe environment variable usage for reliable production deployments.

How this skill works

The skill provides API route patterns and client workflows: create checkout sessions (payment or subscription), return the session URL, and redirect clients to Stripe-hosted pages. It emphasizes loading secret keys at runtime inside API handlers, verifying webhook signatures using raw request bodies, and syncing customer/subscription state to your database. It also includes patterns for customer portal sessions and middleware configuration so payment routes bypass authentication when required.

When to use it

• Adding Stripe payments or subscriptions to a Next.js app
• Implementing secure webhook processing and event-driven billing updates
• Building one-time checkout flows without embedding card fields
• Exposing subscription tiers and managing customer portals
• Testing Stripe integrations locally with the Stripe CLI

Best practices

• Load secret environment variables inside API route functions, not at module initialization
• Return the full checkout session URL and redirect the browser to that URL (do not use redirectToCheckout)
• Verify webhook signatures with Stripe's library using the raw request body
• Use NEXT_PUBLIC_ prefix only for publishable keys; keep secret keys server-side
• Store Stripe customer IDs and subscription state in your database to sync billing lifecycle

Example use cases

• Create a one-time purchase flow: API route creates a payment session and client redirects to session.url
• Offer subscription tiers: fetch prices from Stripe, present tiers, and create subscription checkout sessions
• Handle webhooks: update database on invoice.payment_succeeded and customer.subscription.created events
• Provide a customer portal: generate portal sessions so users manage payment methods and invoices
• Local testing: forward Stripe events to localhost with stripe listen and trigger test events