Stripe Integration Patterns | Bootspring Docs

Battle-tested patterns for Stripe payment integration in Next.js.

Overview#

Stripe is the standard for online payments. This pattern covers:

Stripe SDK setup
Client and server configuration
Customer management
Testing with Stripe CLI
Environment configuration

Prerequisites#

npm install stripe @stripe/stripe-js

Stripe Client Setup#

Configure the Stripe SDK for server-side use.

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

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2024-12-18.acacia',
  typescript: true
})

Client-Side Stripe#

Load Stripe.js for client-side components.

// lib/stripe-client.ts
import { loadStripe, Stripe } from '@stripe/stripe-js'

let stripePromise: Promise<Stripe | null>

export function getStripe() {
  if (!stripePromise) {
    stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!)
  }
  return stripePromise
}

Create Customer#

Create and manage Stripe customers.

// lib/stripe-customers.ts
import { stripe } from './stripe'
import { prisma } from './db'

export async function getOrCreateStripeCustomer(userId: string) {
  const user = await prisma.user.findUnique({
    where: { id: userId }
  })

  if (!user) {
    throw new Error('User not found')
  }

  // Return existing customer
  if (user.stripeCustomerId) {
    return user.stripeCustomerId
  }

  // Create new customer
  const customer = await stripe.customers.create({
    email: user.email,
    name: user.name ?? undefined,
    metadata: {
      userId: user.id
    }
  })

  // Save customer ID to database
  await prisma.user.update({
    where: { id: userId },
    data: { stripeCustomerId: customer.id }
  })

  return customer.id
}

export async function updateStripeCustomer(
  customerId: string,
  data: { email?: string; name?: string }
) {
  return stripe.customers.update(customerId, {
    email: data.email,
    name: data.name
  })
}

One-Time Payment Checkout#

Create a checkout session for one-time payments.

// app/api/checkout/route.ts
import { stripe } from '@/lib/stripe'
import { auth } from '@/auth'
import { getOrCreateStripeCustomer } from '@/lib/stripe-customers'
import { NextResponse } from 'next/server'

export async function POST(req: Request) {
  const session = await auth()

  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const { priceId, quantity = 1 } = await req.json()

  try {
    const customerId = await getOrCreateStripeCustomer(session.user.id)

    const checkoutSession = await stripe.checkout.sessions.create({
      customer: customerId,
      mode: 'payment',
      payment_method_types: ['card'],
      line_items: [{ price: priceId, quantity }],
      success_url: `${process.env.NEXT_PUBLIC_URL}/checkout/success?session_id={CHECKOUT_SESSION_ID}`,
      cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing`,
      metadata: {
        userId: session.user.id
      }
    })

    return NextResponse.json({ url: checkoutSession.url })
  } catch (error) {
    console.error('Checkout error:', error)
    return NextResponse.json(
      { error: 'Failed to create checkout session' },
      { status: 500 }
    )
  }
}

Checkout Button Component#

A reusable button that redirects to Stripe Checkout.

// components/CheckoutButton.tsx
'use client'

import { useState } from 'react'

interface Props {
  priceId: string
  mode?: 'payment' | 'subscription'
  children: React.ReactNode
  className?: string
}

export function CheckoutButton({
  priceId,
  mode = 'payment',
  children,
  className
}: Props) {
  const [loading, setLoading] = useState(false)

  const handleCheckout = async () => {
    setLoading(true)

    try {
      const endpoint = mode === 'subscription'
        ? '/api/subscribe'
        : '/api/checkout'

      const res = await fetch(endpoint, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ priceId })
      })

      const { url, error } = await res.json()

      if (error) {
        alert(error)
        return
      }

      window.location.href = url
    } catch (error) {
      console.error('Checkout error:', error)
      alert('Something went wrong')
    } finally {
      setLoading(false)
    }
  }

  return (
    <button
      onClick={handleCheckout}
      disabled={loading}
      className={className}
    >
      {loading ? 'Loading...' : children}
    </button>
  )
}

Customer Portal#

Allow customers to manage their billing.

// app/api/billing/portal/route.ts
import { stripe } from '@/lib/stripe'
import { auth } from '@/auth'
import { prisma } from '@/lib/db'
import { NextResponse } from 'next/server'

export async function POST() {
  const session = await auth()

  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

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

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

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

  return NextResponse.json({ url: portalSession.url })
}

Environment Variables#

Required environment variables for Stripe.

# .env.local
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

# Price IDs from Stripe Dashboard
STRIPE_PRO_PRICE_ID=price_...
STRIPE_ENTERPRISE_PRICE_ID=price_...

Testing Locally#

Use Stripe CLI to forward webhooks.

# Install Stripe CLI
brew install stripe/stripe-cli/stripe

# Login to Stripe
stripe login

# Forward webhooks to local server
stripe listen --forward-to localhost:3000/api/webhooks/stripe

# Trigger test events
stripe trigger checkout.session.completed
stripe trigger customer.subscription.updated

Test Card Numbers#

Use these test cards during development.

Scenario	Card Number
Success	4242 4242 4242 4242
Decline	4000 0000 0000 0002
3D Secure	4000 0027 6000 3184
Insufficient Funds	4000 0000 0000 9995

Best Practices#

Always verify webhooks - Never trust client-side payment confirmation
Store customer IDs - Link Stripe customers to your user records
Use idempotency keys - Prevent duplicate charges on retries
Handle errors gracefully - Show meaningful messages to users
Log webhook events - Maintain an audit trail for debugging

Checkout - Checkout flow patterns
Subscriptions - Subscription management
Webhooks - Webhook handling