July 11, 2026Web Development12 min readUpdated July 2026

How to Set Up Stripe Payments in Next.js 2026: Checkout, Webhooks, and Subscriptions

Complete guide to integrating Stripe payments in Next.js with App Router. Set up Stripe Checkout, handle webhooks, add subscription billing, manage customer portals, and test with the Stripe CLI. Updated for Next.js 15 and Stripe API 2026.

On this page

Adding payments to a Next.js app is one of those tasks that sounds simple but involves multiple moving parts: server-side API routes, client-side redirects, webhook verification, subscription lifecycle management, and handling edge cases like failed payments and duplicate charges. I integrated Stripe into a SaaS platform serving over 10,000 businesses and ran into most of these issues firsthand. This guide covers everything from initial setup to production-ready subscription billing using Next.js App Router and the latest Stripe API.

What You Will Build

Stripe Checkout for one-time payments
Recurring subscription billing with multiple plans
Webhook handler to sync payment events with your database
Customer portal for managing subscriptions
Server-side payment verification
Testing the full flow with Stripe CLI

Prerequisites

Next.js 14 or 15 with App Router
Node.js 18 or above
A Stripe account (free to create at stripe.com)
A database for storing user and subscription data (PostgreSQL with Prisma recommended)
Basic familiarity with TypeScript and React Server Components

Step 1: Install Stripe Packages

You need two packages: `stripe` for server-side API calls and `@stripe/stripe-js` for the client-side Stripe.js loader. The server-side package handles creating checkout sessions, managing subscriptions, and verifying webhooks. The client-side package loads Stripe.js for redirecting users to Checkout.

Install Stripe packages

1npm install stripe @stripe/stripe-js

Step 2: Set Up Environment Variables

Go to the Stripe Dashboard, navigate to Developers and then API keys. Copy your publishable key and secret key. For local development use the test mode keys. Never expose your secret key to the client.

Environment variables for Stripe

1# .env.local
2STRIPE_SECRET_KEY=sk_test_your_secret_key_here
3NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key_here
4STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
5NEXT_PUBLIC_APP_URL=http://localhost:3000

The STRIPE_WEBHOOK_SECRET is generated when you set up the webhook endpoint. We will get this value in a later step.

Step 3: Create the Stripe Server Client

Create a shared Stripe instance that you import wherever you need to call the Stripe API on the server. This keeps your Stripe version and config consistent across all API routes and server actions.

Shared Stripe server instance

1// lib/stripe.ts
2import Stripe from 'stripe';
3
4export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
5  apiVersion: '2025-12-18.acacia',
6  typescript: true,
7});

Step 4: Create the Client-Side Stripe Loader

For client-side operations like redirecting to Stripe Checkout, you need to load Stripe.js. Use the `loadStripe` function from @stripe/stripe-js and wrap it so it only loads once.

Client-side Stripe.js loader (singleton)

1// lib/stripe-client.ts
2import { loadStripe } from '@stripe/stripe-js';
3
4let stripePromise: ReturnTypetypeof loadStripe;
5
6export function getStripe() {
7  if (!stripePromise) {
8    stripePromise = loadStripe(
9      process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!
10    );
11  }
12  return stripePromise;
13}

Step 5: Create a Checkout Session API Route

This is the core of Stripe integration. When a user clicks a buy or subscribe button, your frontend calls this API route. The route creates a Stripe Checkout Session on the server and returns the session URL. The frontend then redirects the user to Stripe hosted checkout page where they enter payment details.

Checkout session API route

1// app/api/checkout/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { stripe } from '@/lib/stripe';
4
5export async function POST(req: NextRequest) {
6  try {
7    const { priceId, userId, email } = await req.json();
8
9    const session = await stripe.checkout.sessions.create({
10      mode: 'subscription', // Use 'payment' for one-time charges
11      payment_method_types: ['card'],
12      customer_email: email,
13      line_items: [
14        {
15          price: priceId,
16          quantity: 1,
17        },
18      ],
19      metadata: {
20        userId,
21      },
22      success_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard?success=true`,
23      cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing?canceled=true`,
24    });
25
26    return NextResponse.json({ url: session.url });
27  } catch (error: any) {
28    console.error('Stripe checkout error:', error.message);
29    return NextResponse.json(
30      { error: error.message },
31      { status: 500 }
32    );
33  }
34}

Important details: the `metadata` field lets you attach your internal userId to the Stripe session. You will need this in the webhook to link the Stripe subscription back to your user in the database. The `mode` can be `subscription` for recurring billing or `payment` for one-time charges.

Step 6: Create the Pricing Page with Checkout Button

Create a pricing page that displays your plans and handles the checkout redirect. When the user clicks a plan, the component calls your checkout API route, gets back the Stripe Checkout URL, and redirects the browser.

Pricing page with checkout redirect

1// app/pricing/page.tsx
2'use client';
3
4import { useState } from 'react';
5
6const plans = [
7  {
8    name: 'Starter',
9    price: '$19/mo',
10    priceId: 'price_starter_monthly_id', // From Stripe Dashboard
11    features: ['5 projects', '10GB storage', 'Email support'],
12  },
13  {
14    name: 'Pro',
15    price: '$49/mo',
16    priceId: 'price_pro_monthly_id',
17    features: ['Unlimited projects', '100GB storage', 'Priority support'],
18  },
19];
20
21export default function PricingPage() {
22  const [loading, setLoading] = useStatestring | null(null);
23
24  async function handleCheckout(priceId: string) {
25    setLoading(priceId);
26
27    try {
28      const res = await fetch('/api/checkout', {
29        method: 'POST',
30        headers: { 'Content-Type': 'application/json' },
31        body: JSON.stringify({
32          priceId,
33          userId: 'user_123', // Get from your auth session
34          email: 'user@example.com', // Get from your auth session
35        }),
36      });
37
38      const data = await res.json();
39
40      if (data.url) {
41        window.location.href = data.url;
42      }
43    } catch (error) {
44      console.error('Checkout error:', error);
45    } finally {
46      setLoading(null);
47    }
48  }
49
50  return (
51    div className="max-w-4xl mx-auto py-16 px-4"
52      h1 className="text-3xl font-bold text-center mb-12"Pricing/h1
53      div className="grid md:grid-cols-2 gap-8"
54        {plans.map((plan) = (
55          div key={plan.name} className="border rounded-lg p-8"
56            h2 className="text-xl font-semibold"{plan.name}/h2
57            p className="text-3xl font-bold mt-4"{plan.price}/p
58            ul className="mt-6 space-y-2"
59              {plan.features.map((f) = (
60                li key={f}✓ {f}/li
61              ))}
62            /ul
63            button
64              {() = handleCheckout(plan.priceId)}
65              disabled={loading === plan.priceId}
66              className="mt-8 w-full bg-blue-600 text-white py-3 rounded-lg"
67            
68              {loading === plan.priceId ? 'Redirecting...' : 'Subscribe'}
69            /button
70          /div
71        ))}
72      /div
73    /div
74  );
75}

Step 7: Handle Webhooks

This is the most critical part of Stripe integration and the part most tutorials skip or get wrong. Webhooks are how Stripe tells your app about payment events: successful payments, failed charges, subscription renewals, cancellations, and refunds. You must never rely on the success_url redirect alone because users can close the browser before reaching it. The webhook is the only reliable way to know a payment succeeded.

Stripe webhook handler with all subscription events

1// app/api/webhooks/stripe/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { stripe } from '@/lib/stripe';
4import Stripe from 'stripe';
5
6// Disable body parsing - Stripe needs the raw body for signature verification
7export const runtime = 'nodejs';
8
9export async function POST(req: NextRequest) {
10  const body = await req.text();
11  const signature = req.headers.get('stripe-signature')!;
12
13  let event: Stripe.Event;
14
15  try {
16    event = stripe.webhooks.constructEvent(
17      body,
18      signature,
19      process.env.STRIPE_WEBHOOK_SECRET!
20    );
21  } catch (error: any) {
22    console.error('Webhook signature verification failed:', error.message);
23    return NextResponse.json(
24      { error: 'Invalid signature' },
25      { status: 400 }
26    );
27  }
28
29  try {
30    switch (event.type) {
31      case 'checkout.session.completed': {
32        const session = event.data.object as Stripe.Checkout.Session;
33        const userId = session.metadata?.userId;
34        const subscripti session.subscription as string;
35        const customerId = session.customer as string;
36
37        // Save to your database
38        // await db.user.update({
39        //   where: { id: userId },
40        //   data: {
41        //     stripeCustomerId: customerId,
42        //     stripeSubscriptionId: subscriptionId,
43        //     plan: 'pro',
44        //     subscriptionStatus: 'active',
45        //   },
46        // });
47
48        console.log(`Subscription created for user ${userId}`);
49        break;
50      }
51
52      case 'invoice.payment_succeeded': {
53        const invoice = event.data.object as Stripe.Invoice;
54        const subscripti invoice.subscription as string;
55
56        // Renewal succeeded - update billing period
57        // await db.subscription.update({
58        //   where: { stripeSubscriptionId: subscriptionId },
59        //   data: {
60        //     currentPeriodEnd: new Date(invoice.period_end * 1000),
61        //     subscriptionStatus: 'active',
62        //   },
63        // });
64
65        console.log(`Invoice paid for subscription ${subscriptionId}`);
66        break;
67      }
68
69      case 'invoice.payment_failed': {
70        const invoice = event.data.object as Stripe.Invoice;
71        const subscripti invoice.subscription as string;
72
73        // Payment failed - mark subscription as past due
74        // await db.subscription.update({
75        //   where: { stripeSubscriptionId: subscriptionId },
76        //   data: { subscriptionStatus: 'past_due' },
77        // });
78
79        console.log(`Payment failed for subscription ${subscriptionId}`);
80        break;
81      }
82
83      case 'customer.subscription.deleted': {
84        const subscription = event.data.object as Stripe.Subscription;
85
86        // Subscription canceled or expired
87        // await db.subscription.update({
88        //   where: { stripeSubscriptionId: subscription.id },
89        //   data: {
90        //     subscriptionStatus: 'canceled',
91        //     plan: 'free',
92        //   },
93        // });
94
95        console.log(`Subscription ${subscription.id} canceled`);
96        break;
97      }
98
99      case 'customer.subscription.updated': {
100        const subscription = event.data.object as Stripe.Subscription;
101
102        // Plan changed, billing updated, or trial ended
103        // await db.subscription.update({
104        //   where: { stripeSubscriptionId: subscription.id },
105        //   data: {
106        //     subscriptionStatus: subscription.status,
107        //     priceId: subscription.items.data[0].price.id,
108        //   },
109        // });
110
111        console.log(`Subscription ${subscription.id} updated`);
112        break;
113      }
114
115      default:
116        console.log(`Unhandled event type: ${event.type}`);
117    }
118
119    return NextResponse.json({ received: true });
120  } catch (error: any) {
121    console.error('Webhook handler error:', error.message);
122    return NextResponse.json(
123      { error: 'Webhook handler failed' },
124      { status: 500 }
125    );
126  }
127}

Key points about this webhook handler: always verify the signature before processing any event. The raw body must be passed to constructEvent, not the parsed JSON. Handle at least these five events for subscriptions: checkout.session.completed, invoice.payment_succeeded, invoice.payment_failed, customer.subscription.deleted, and customer.subscription.updated. Always return a 200 response quickly, even if your database write takes time, to prevent Stripe from retrying.

Step 8: Add the Customer Portal

Stripe provides a hosted customer portal where users can update their payment method, switch plans, cancel their subscription, and view invoice history. You do not need to build any of this UI yourself. Create an API route that generates a portal session URL and redirect the user.

Customer portal API route

1// app/api/portal/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { stripe } from '@/lib/stripe';
4
5export async function POST(req: NextRequest) {
6  try {
7    const { customerId } = await req.json();
8
9    const session = await stripe.billingPortal.sessions.create({
10      customer: customerId,
11      return_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard`,
12    });
13
14    return NextResponse.json({ url: session.url });
15  } catch (error: any) {
16    console.error('Portal error:', error.message);
17    return NextResponse.json(
18      { error: error.message },
19      { status: 500 }
20    );
21  }
22}

Before using the customer portal, enable it in the Stripe Dashboard under Settings then Billing then Customer portal. Configure which features you want to allow: plan switching, cancellation, payment method updates, and invoice history.

Step 9: Create Products and Prices in Stripe Dashboard

Before testing, you need to create products and prices in the Stripe Dashboard. Go to Products, click Add Product, enter a name and description, then add a recurring price. You can also create prices using the Stripe API or CLI.

Create Stripe products and prices via CLI

1# Create products and prices via Stripe CLI
2stripe products create --name="Starter Plan" --description="5 projects, 10GB storage"
3
4# Create a recurring price for the product
5stripe prices create \
6  --product="prod_xxxxx" \
7  --unit-amount=1900 \
8  --currency=usd \
9  --recurring-interval=month
10
11# Create a one-time price
12stripe prices create \
13  --product="prod_xxxxx" \
14  --unit-amount=9900 \
15  --currency=usd

Copy the price IDs (starting with price_) and use them in your pricing page component. For one-time payments, change the checkout session mode from subscription to payment.

Step 10: Test with Stripe CLI

The Stripe CLI lets you test webhooks locally by forwarding Stripe events to your localhost. Install the CLI, log in, and start forwarding events to your webhook route.

Install and run Stripe CLI for local webhook testing

1# Install Stripe CLI
2# macOS
3brew install stripe/stripe-cli/stripe
4
5# Windows (scoop)
6scoop install stripe
7
8# Login
9stripe login
10
11# Forward webhooks to your local server
12stripe listen --forward-to localhost:3000/api/webhooks/stripe

The CLI will print a webhook signing secret starting with whsec_. Copy this value and add it to your .env.local as STRIPE_WEBHOOK_SECRET. This secret is different from your production webhook secret.

Test Card Numbers

Stripe test card numbers

1# Successful payment
24242 4242 4242 4242
3
4# Payment requires authentication (3D Secure)
54000 0025 0000 3155
6
7# Payment declined
84000 0000 0000 0002
9
10# Insufficient funds
114000 0000 0000 9995
12
13# Use any future expiry date and any 3-digit CVC

Trigger Test Events

Trigger test webhook events via Stripe CLI

1# Trigger a specific webhook event for testing
2stripe trigger checkout.session.completed
3stripe trigger invoice.payment_succeeded
4stripe trigger invoice.payment_failed
5stripe trigger customer.subscription.deleted

Step 11: One-Time Payments Instead of Subscriptions

If your app sells one-time products instead of subscriptions, change the checkout session mode to payment and use a one-time price ID instead of a recurring one. The webhook event to listen for is checkout.session.completed with mode payment instead of subscription.

Checkout session for one-time payments

1// One-time payment checkout session
2const session = await stripe.checkout.sessions.create({
3  mode: 'payment', // Changed from 'subscription'
4  payment_method_types: ['card'],
5  customer_email: email,
6  line_items: [
7    {
8      price: 'price_one_time_id',
9      quantity: 1,
10    },
11  ],
12  metadata: { userId },
13  success_url: `${process.env.NEXT_PUBLIC_APP_URL}/success`,
14  cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
15});

Step 12: Deploy Webhook to Production

When deploying to production on Vercel, Netlify, or AWS, you need to register a production webhook endpoint in the Stripe Dashboard.

Go to Stripe Dashboard then Developers then Webhooks
Click Add endpoint
Enter your production URL: https://yourdomain.com/api/webhooks/stripe
Select events to listen to: checkout.session.completed, invoice.payment_succeeded, invoice.payment_failed, customer.subscription.deleted, customer.subscription.updated
Copy the signing secret (whsec_) and add it to your production environment variables as STRIPE_WEBHOOK_SECRET
Switch your STRIPE_SECRET_KEY from sk_test to sk_live in production environment

Common Mistakes to Avoid

Never rely on the success_url redirect to confirm payment. Users can close the browser. Always use webhooks.
Never parse the request body as JSON before passing it to constructEvent. Stripe needs the raw body string for signature verification.
Never expose your STRIPE_SECRET_KEY on the client side. Only the NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY should be public.
Always handle invoice.payment_failed in your webhook. Subscriptions can fail silently without this.
Always return a 200 response from your webhook handler quickly. If Stripe does not get a 200 within a few seconds, it will retry the event up to 3 days.
Do not use the same webhook secret for local testing and production. The Stripe CLI generates a different secret than your dashboard endpoint.
Store the Stripe customer ID in your database. Creating a new customer for every checkout leads to duplicate customers.

Full Project Structure

Complete project folder structure

1your-nextjs-app/
2├── app/
3│   ├── api/
4│   │   ├── checkout/
5│   │   │   └── route.ts         # Creates Checkout sessions
6│   │   ├── portal/
7│   │   │   └── route.ts         # Creates Customer Portal sessions
8│   │   └── webhooks/
9│   │       └── stripe/
10│   │           └── route.ts     # Handles all Stripe webhook events
11│   ├── pricing/
12│   │   └── page.tsx             # Pricing page with plan cards
13│   └── dashboard/
14│       └── page.tsx             # Post-checkout dashboard
15├── lib/
16│   ├── stripe.ts                # Server-side Stripe instance
17│   └── stripe-client.ts         # Client-side Stripe.js loader
18└── .env.local                   # Stripe API keys

Quick Start Checklist

Install stripe and @stripe/stripe-js
Add STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, and STRIPE_WEBHOOK_SECRET to .env.local
Create lib/stripe.ts for server-side and lib/stripe-client.ts for client-side
Create the checkout API route at app/api/checkout/route.ts
Create the webhook handler at app/api/webhooks/stripe/route.ts
Create the customer portal route at app/api/portal/route.ts
Create products and prices in Stripe Dashboard
Test locally with stripe listen --forward-to localhost:3000/api/webhooks/stripe
Use test card 4242 4242 4242 4242 for successful payments
Register a production webhook endpoint before going live
Switch from test to live API keys in production

Official-Style Summary

Integrating Stripe with Next.js App Router involves four main pieces: a checkout API route that creates Stripe Checkout Sessions, a webhook handler that receives and verifies payment events from Stripe, a customer portal route for subscription management, and client-side code that redirects users to the Stripe-hosted checkout page. The webhook handler is the most important part because it is the only reliable way to know a payment succeeded. Always verify the webhook signature using the raw request body, handle at least five subscription events (checkout.session.completed, invoice.payment_succeeded, invoice.payment_failed, customer.subscription.deleted, customer.subscription.updated), and return a 200 response immediately. Use the Stripe CLI for local testing, create separate webhook secrets for development and production, and never expose your secret key on the client side.

FAQ

Do I need @stripe/react-stripe-js for Next.js?

Not necessarily. For Stripe Checkout (the hosted payment page), you only need the stripe server package and @stripe/stripe-js for the redirect. The @stripe/react-stripe-js package is only needed if you want to build a custom payment form with Stripe Elements embedded directly in your page instead of using the hosted Checkout.

Can I use Stripe with Next.js Server Actions instead of API routes?

Yes. You can create Stripe Checkout sessions inside a Server Action instead of an API route. However, webhook handlers must remain as API routes because Stripe sends POST requests to a URL endpoint. Server Actions are triggered by form submissions from the client, not external HTTP requests.

Why is my Stripe webhook returning 400 or signature verification failed?

The most common cause is parsing the request body as JSON before passing it to constructEvent. Stripe needs the raw body string, not parsed JSON. In Next.js App Router, use req.text() instead of req.json() to get the raw body. Also make sure your STRIPE_WEBHOOK_SECRET matches the endpoint: the Stripe CLI generates a different secret than your production dashboard webhook.

How do I handle Stripe in a Next.js middleware or edge runtime?

The Stripe Node.js SDK does not work in edge runtimes because it depends on Node.js APIs. Your webhook and checkout routes must use the Node.js runtime. Add export const runtime = 'nodejs' at the top of your route file if your Next.js project defaults to edge.

Should I use Stripe Checkout or Stripe Elements?

Use Stripe Checkout (the hosted page) for most apps. It handles payment UI, 3D Secure authentication, address collection, tax calculation, and PCI compliance automatically. Stripe Elements gives you more design control by embedding payment fields directly in your page, but you have to handle more logic yourself. Checkout is faster to implement and covers more edge cases out of the box.

How do I test failed payments and subscription cancellations locally?

Use the Stripe CLI to trigger specific events with stripe trigger invoice.payment_failed or stripe trigger customer.subscription.deleted. For testing failed card payments through the actual checkout flow, use the test card number 4000 0000 0000 0002 which always declines.

Shahmeer Rizwan

Full-Stack Developer

Location

Follow us

Blog - Insights & Resources