Stripe Payments in Next.js 15 — The Setup I Use for Every SaaS Project

Question

Every SaaS project eventually needs the same thing, a way to charge people. Stripe handles the actual payment processing, but wiring it into Next.js correctly, especially getting webhooks right, is where most of the real work sits.

Here is the setup I use for checkout and subscriptions in every SaaS project.

---

1. The Stripe Client

// lib/stripe.ts
import Stripe from 'stripe';

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
  apiVersion: '2024-11-20.acacia',
  typescript: true,
});

One client, imported wherever needed. Nothing fancy, but keeping it in one file means the API version and config only need to be set once.

---

2. Creating a Checkout Session

The checkout flow starts with a Server Action that creates a Stripe Checkout Session and redirects the user to Stripe's hosted payment page.

// actions/checkout.ts
'use server';
import { stripe } from '@/lib/stripe';
import { getSession } from '@/lib/auth';
import { redirect } from 'next/navigation';

export async function createCheckoutSession(priceId: string) {
  const session = await getSession();
  if (!session) redirect('/login');

  const checkoutSession = await stripe.checkout.sessions.create({
    mode: 'subscription',
    payment_method_types: ['card'],
    line_items: [{ price: priceId, quantity: 1 }],
    customer_email: session.email,
    success_url: `${process.env.NEXT_PUBLIC_URL}/dashboard?success=true`,
    cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing?canceled=true`,
    metadata: {
      userId: session.userId,
    },
  });

  redirect(checkoutSession.url as string);
}

The metadata.userId here matters more than it looks. Stripe has no idea who your user is beyond what you attach in metadata, and the webhook handler needs this to know which account to update once payment completes.

// components/PricingCard.tsx
import { createCheckoutSession } from '@/actions/checkout';

export function PricingCard({ priceId, name, price }: { priceId: string; name: string; price: string }) {
  return (
    <form action={createCheckoutSession.bind(null, priceId)}>
      <h3>{name}</h3>
      <p>{price}/month</p>
      <button type="submit">Subscribe</button>
    </form>
  );
}

---

3. Why Webhooks Are Not Optional

This is the part people try to skip, and it always causes problems. It is tempting to just update the database directly on the success_url page after redirect. Do not do this. The redirect happens in the user's browser, which means it can fail to load, get closed early, or never fire at all, and your database never finds out the payment actually succeeded.

Webhooks are Stripe calling your server directly, independent of whether the user's browser is even still open. This is the only reliable source of truth for what actually happened with a payment.

// app/api/webhooks/stripe/route.ts
import { stripe } from '@/lib/stripe';
import { connectDB } from '@/lib/db';
import User from '@/models/User';
import { headers } from 'next/headers';
import Stripe from 'stripe';

const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET as string;

export async function POST(request: Request) {
  const body = await request.text();
  const headersList = await headers();
  const signature = headersList.get('stripe-signature') as string;

  let event: Stripe.Event;

  try {
    event = stripe.webhooks.constructEvent(body, signature, webhookSecret);
  } catch (err) {
    return new Response('Invalid signature', { status: 400 });
  }

  await connectDB();

  switch (event.type) {
    case 'checkout.session.completed': {
      const session = event.data.object as Stripe.Checkout.Session;
      const userId = session.metadata?.userId;

      await User.findByIdAndUpdate(userId, {
        stripeCustomerId: session.customer as string,
        stripeSubscriptionId: session.subscription as string,
        subscriptionStatus: 'active',
      });
      break;
    }

    case 'customer.subscription.deleted': {
      const subscription = event.data.object as Stripe.Subscription;
      await User.findOneAndUpdate(
        { stripeSubscriptionId: subscription.id },
        { subscriptionStatus: 'canceled' }
      );
      break;
    }

    case 'customer.subscription.updated': {
      const subscription = event.data.object as Stripe.Subscription;
      await User.findOneAndUpdate(
        { stripeSubscriptionId: subscription.id },
        { subscriptionStatus: subscription.status }
      );
      break;
    }
  }

  return new Response('OK', { status: 200 });
}

stripe.webhooks.constructEvent verifies the request actually came from Stripe using the signature header, not from anyone who happened to guess your webhook URL. Skipping this check means anyone could send a fake checkout.session.completed payload and grant themselves a subscription for free.

---

4. Route Handlers Need Raw Body, Not Parsed JSON

This trips people up specifically with Next.js. Signature verification needs the exact raw request body, byte for byte, not a parsed and re-serialized version of it.

export async function POST(request: Request) {
  const body = await request.text(); // raw text, not request.json()
  // ...
}

Using request.json() here silently breaks signature verification, since JSON parsing and re-stringifying can change whitespace and key order in ways that make the signature no longer match.

---

5. Registering the Webhook Locally and in Production

For local development, the Stripe CLI forwards events to your local server:

stripe listen --forward-to localhost:3000/api/webhooks/stripe

This prints a webhook signing secret specific to your CLI session, used as STRIPE_WEBHOOK_SECRET locally. In production, the webhook endpoint gets registered in the Stripe dashboard pointing at your real domain, with its own separate signing secret, different from the local one.

---

6. Checking Subscription Status Elsewhere in the App

Once the webhook keeps subscriptionStatus in sync, the rest of the app just reads it, no direct Stripe API calls needed on every page load.

// lib/queries/users.ts
export async function requireActiveSubscription() {
  const session = await getSession();
  if (!session) redirect('/login');

  await connectDB();
  const user = await User.findById(session.userId).lean();

  if (user?.subscriptionStatus !== 'active') {
    redirect('/pricing');
  }

  return user;
}

// app/(dashboard)/layout.tsx
import { requireActiveSubscription } from '@/lib/queries/users';

export default async function DashboardLayout({ children }: { children: React.ReactNode }) {
  await requireActiveSubscription();
  return <div>{children}</div>;
}

The database is the source of truth for whether a user has access, kept accurate by webhooks. The app never needs to ask Stripe directly just to render a page.

---

7. Handling Failed Payments

Subscriptions do not just cancel cleanly, cards expire, charges get declined. Stripe retries automatically, but your app needs to know when a subscription enters a past-due state:

case 'invoice.payment_failed': {
  const invoice = event.data.object as Stripe.Invoice;
  await User.findOneAndUpdate(
    { stripeCustomerId: invoice.customer as string },
    { subscriptionStatus: 'past_due' }
  );
  break;
}

Whether past_due still grants access or restricts it is a product decision, not a technical one, but the webhook is what makes that state visible to your app in the first place.

---

Summary

Piece	Handles
Checkout Session	Starting a subscription, redirecting to Stripe's hosted page
Webhook endpoint	The only reliable source of truth for payment events
Signature verification	Confirming events actually came from Stripe
Raw request body	Required for signature verification to succeed
Database subscriptionStatus	What the rest of the app actually checks, kept in sync by webhooks
invoice.payment_failed	Catching failed renewals, not just initial signups

The core lesson, learned the hard way on an early project: never trust the browser redirect as confirmation that a payment succeeded. The webhook is the only event that cannot be skipped, closed early, or spoofed without a valid signature, which makes it the only place worth writing real subscription logic.

I use this exact checkout and webhook setup across every SaaS project I build with subscription billing.

Get the templates: https://pixelanas.gumroad.com

Have you had a webhook edge case bite you in production? Drop it below 👇

---

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751