How to Securely Integrate Stripe Subscriptions in a Next.js App2026 Guide

# Stripe API Keys — NEVER prefix secret key with NEXT_PUBLIC_
STRIPE_SECRET_KEY="sk_test_51..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_51..."

# Webhook signing secret — different for test and live mode
STRIPE_WEBHOOK_SECRET="whsec_..."

# Your app's base URL (used in redirect URLs)
NEXT_PUBLIC_APP_URL="http://localhost:3000"

import Stripe from 'stripe';

// Pin to a specific API version — review Stripe changelog before upgrading
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2026-01-28',
  typescript: true,
});

// ONLY import this file in: Route Handlers, Server Actions, Server Components
// NEVER import in: 'use client' components, hooks, or pages router _app.tsx

import { stripe } from '@/lib/stripe';
import { db } from '@/lib/db';

export async function createStripeCustomer(
  userId: string,
  email: string,
  name: string
) {
  const customer = await stripe.customers.create({
    email,
    name,
    metadata: { userId },  // Links Stripe customer back to your user ID
  });

  // Persist the Stripe customer ID in your database
  await db.user.update({
    where: { id: userId },
    data: { stripeCustomerId: customer.id },
  });

  return customer.id;
}

import { NextRequest, NextResponse } from 'next/server';
import { stripe } from '@/lib/stripe';
import { getServerSession } from '@/lib/auth';
import { db } from '@/lib/db';

// Server-side price ID mapping — client never sees amounts
const PRICE_IDS: Record<string, string> = {
  starter_monthly: process.env.STRIPE_PRICE_STARTER_MONTHLY!,
  pro_monthly:     process.env.STRIPE_PRICE_PRO_MONTHLY!,
  pro_annual:      process.env.STRIPE_PRICE_PRO_ANNUAL!,
};

export async function POST(req: NextRequest) {
  const session = await getServerSession();
  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorised' }, { status: 401 });
  }

  const { planKey } = await req.json();

  // Validate planKey against known values — reject anything unexpected
  const priceId = PRICE_IDS[planKey];
  if (!priceId) {
    return NextResponse.json({ error: 'Invalid plan' }, { status: 400 });
  }

  // Fetch the Stripe customer ID from your database
  const user = await db.user.findUnique({ where: { id: session.user.id } });

  const checkoutSession = await stripe.checkout.sessions.create({
    mode: 'subscription',
    customer: user?.stripeCustomerId,   // Re-use existing Stripe customer
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard?upgraded=true`,
    cancel_url:  `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
    metadata: { userId: session.user.id },
    allow_promotion_codes: true,
  });

  return NextResponse.json({ url: checkoutSession.url });
}

import { NextRequest } from 'next/server';
import { headers } from 'next/headers';
import Stripe from 'stripe';
import { stripe } from '@/lib/stripe';
import { db } from '@/lib/db';

export async function POST(req: NextRequest) {
  // ✓ Read as raw text — NEVER call req.json() here
  const body = await req.text();
  const signature = (await headers()).get('stripe-signature');

  if (!signature) {
    return new Response('Missing stripe-signature header', { status: 400 });
  }

  let event: Stripe.Event;

  try {
    // constructEvent verifies the signature against the raw body
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err: any) {
    // Log the error but return 400 — do NOT process unverified events
    console.error('Webhook signature verification failed:', err.message);
    return new Response(`Webhook error: ${err.message}`, { status: 400 });
  }

  // Signature verified — safe to process the event
  try {
    await handleWebhookEvent(event);
  } catch (err) {
    // Return 500 so Stripe retries the delivery
    console.error('Webhook handler error:', err);
    return new Response('Internal error', { status: 500 });
  }

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

async function handleWebhookEvent(event: Stripe.Event) {
  switch (event.type) {

    case 'checkout.session.completed': {
      const session = event.data.object as Stripe.Checkout.Session;
      if (session.mode === 'subscription' && session.subscription) {
        await db.user.update({
          where: { id: session.metadata!.userId },
          data: {
            subscriptionId:     session.subscription as string,
            subscriptionStatus: 'active',
          },
        });
      }
      break;
    }

    case 'customer.subscription.updated': {
      const sub = event.data.object as Stripe.Subscription;
      await db.user.updateMany({
        where: { subscriptionId: sub.id },
        data: { subscriptionStatus: sub.status },
      });
      break;
    }

    case 'customer.subscription.deleted': {
      const sub = event.data.object as Stripe.Subscription;
      await db.user.updateMany({
        where: { subscriptionId: sub.id },
        data: { subscriptionStatus: 'cancelled' },
      });
      break;
    }

    case 'invoice.payment_failed': {
      const invoice = event.data.object as Stripe.Invoice;
      // Notify user, trigger dunning email, update billing status
      console.log(`Payment failed for customer: ${invoice.customer}`);
      break;
    }

    default:
      // Silently ignore events we don't handle
  }
}

import { NextRequest, NextResponse } from 'next/server';
import { stripe } from '@/lib/stripe';
import { getServerSession } from '@/lib/auth';
import { db } from '@/lib/db';

export async function POST(req: NextRequest) {
  const session = await getServerSession();
  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorised' }, { status: 401 });
  }

  const user = await db.user.findUnique({ where: { id: session.user.id } });

  if (!user?.stripeCustomerId) {
    return NextResponse.json({ error: 'No billing account found' }, { status: 404 });
  }

  const portalSession = await stripe.billingPortal.sessions.create({
    customer:   user.stripeCustomerId,
    return_url: `${process.env.NEXT_PUBLIC_APP_URL}/dashboard`,
  });

  // Redirect directly to the portal URL
  return NextResponse.redirect(portalSession.url);
}

import { NextRequest, NextResponse } from 'next/server';
import { getSessionFromCookie } from '@/lib/auth';
import { db } from '@/lib/db';

export async function middleware(req: NextRequest) {
  // Only run on protected routes
  if (!req.nextUrl.pathname.startsWith('/dashboard')) {
    return NextResponse.next();
  }

  const session = await getSessionFromCookie(req);
  if (!session) {
    return NextResponse.redirect(new URL('/login', req.url));
  }

  // Check subscription status from DB — never from client state
  const user = await db.user.findUnique({
    where:  { id: session.userId },
    select: { subscriptionStatus: true },
  });

  if (user?.subscriptionStatus !== 'active') {
    return NextResponse.redirect(new URL('/pricing', req.url));
  }

  return NextResponse.next();
}

export const config = {
  matcher: ['/dashboard/:path*', '/app/:path*'],
};