Stripe Payment Integration: Complete Dev Guide 2026

// Next.js App Router — Create checkout session (Server Action)

"use server";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2026-01-28",
});

export async function createCheckoutSession(priceId: string, userId: string) {
  const session = await stripe.checkout.sessions.create({
    mode: "payment",                   // or "subscription" for recurring
    payment_method_types: ["card"],    // or remove to use automatic_payment_methods
    automatic_payment_methods: { enabled: true }, // recommended
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing`,
    client_reference_id: userId,       // link session to your user ID
    customer_creation: "always",       // create Stripe Customer for reuse
    metadata: { userId },              // accessible in webhook payload
    allow_promotion_codes: true,       // enable discount codes
  });
  return session.url;
}

// Server Action invocation pattern (Next.js 15)

// Client component
"use client";
import { useTransition } from "react";
import { createCheckoutSession } from "@/app/actions/stripe";

export function CheckoutButton({ priceId }: { priceId: string }) {
  const [isPending, startTransition] = useTransition();

  const handleCheckout = () => {
    startTransition(async () => {
      const url = await createCheckoutSession(priceId, userId);
      if (url) { window.location.href = url; }
    });
  };

  return (
    <button disabled={isPending} onClick={handleCheckout} type="button">
      {isPending ? "Redirecting..." : "Purchase"}
    </button>
  );
}

// Subscription checkout with trial period

const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: monthlyPriceId, quantity: 1 }],
  subscription_data: {
    trial_period_days: 14,             // 14-day free trial
    metadata: { userId },
  },
  success_url: `${origin}/dashboard?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${origin}/pricing`,
  customer_email: user.email,          // pre-fill if not using customer ID
  allow_promotion_codes: true,
});

// Key subscription statuses to handle in webhooks:
// trialing   → access granted (trial period)
// active     → access granted (paid)
// past_due   → payment failed, retrying (warn user)
// unpaid     → max retries exceeded (revoke access)
// canceled   → subscription ended (revoke access)
// incomplete → requires payment action (3DS pending)

// Next.js App Router webhook route — /app/api/webhooks/stripe/route.ts

import Stripe from "stripe";
import { NextRequest, NextResponse } from "next/server";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;

export async function POST(request: NextRequest) {
  const body = await request.text(); // CRITICAL: raw text, not JSON
  const signature = request.headers.get("stripe-signature");

  if (!signature) {
    return NextResponse.json({ error: "No signature" }, { status: 400 });
  }

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, signature, webhookSecret);
  } catch (err) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
  }

  // Always return 200 for events you don't handle
  try {
    switch (event.type) {
      case "checkout.session.completed": {
        const session = event.data.object as Stripe.Checkout.Session;
        await handleCheckoutComplete(session);
        break;
      }
      case "customer.subscription.updated":
      case "customer.subscription.deleted": {
        const subscription = event.data.object as Stripe.Subscription;
        await handleSubscriptionChange(subscription);
        break;
      }
      case "invoice.payment_failed": {
        const invoice = event.data.object as Stripe.Invoice;
        await handlePaymentFailed(invoice);
        break;
      }
    }
  } catch (err) {
    // Log the error but still return 200 to prevent Stripe retries
    // for application-level errors (DB down, etc.)
    // Use a dead letter queue for failed events
    return NextResponse.json({ error: "Processing failed" }, { status: 500 });
  }

  return NextResponse.json({ received: true });
}

// Stripe error handling pattern

import Stripe from "stripe";

async function createCharge() {
  try {
    const paymentIntent = await stripe.paymentIntents.create({ ... });
  } catch (err) {
    if (err instanceof Stripe.errors.StripeCardError) {
      // Card declined — show user-friendly message
      switch (err.code) {
        case "card_declined":
          return { error: "Your card was declined. Please use a different card." };
        case "insufficient_funds":
          return { error: "Insufficient funds. Please use a different card." };
        case "expired_card":
          return { error: "Your card has expired. Please update your payment method." };
        case "incorrect_cvc":
          return { error: "Incorrect CVC. Please check your card details." };
        case "processing_error":
          return { error: "A processing error occurred. Please try again." };
        default:
          return { error: err.message };
      }
    } else if (err instanceof Stripe.errors.StripeRateLimitError) {
      // Too many requests — implement exponential backoff
    } else if (err instanceof Stripe.errors.StripeInvalidRequestError) {
      // Invalid parameters — log and fix the code
    } else if (err instanceof Stripe.errors.StripeConnectionError) {
      // Network issue — safe to retry
    } else {
      throw err; // Unknown error — let it propagate
    }
  }
}