Stripe 결제 연동 실전 튜토리얼 — Next.js Checkout, Webhook, 구독 결제 완전 구현

패키지 설치 (npm)
npm install stripe @stripe/stripe-js @stripe/react-stripe-js

.env.local
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxx
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxx

lib/stripe.ts — 서버용 인스턴스
import Stripe from 'stripe'

if (!process.env.STRIPE_SECRET_KEY) {
  throw new Error('STRIPE_SECRET_KEY is not set')
}

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: '2025-04-30',
  typescript: true,
})

lib/stripe-client.ts — 클라이언트용 Promise
import { loadStripe } from '@stripe/stripe-js'

let stripePromise: ReturnType<typeof loadStripe>

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

app/actions/checkout.ts — 서버 액션
'use server'

import { redirect } from 'next/navigation'
import { stripe } from '@/lib/stripe'

export async function createCheckoutSession(priceId: string) {
  const session = await stripe.checkout.sessions.create({
    mode: 'payment',            // 일회성 결제
    line_items: [
      {
        price: priceId,
        quantity: 1,
      },
    ],
    success_url: `${process.env.NEXT_PUBLIC_BASE_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.NEXT_PUBLIC_BASE_URL}/cancel`,
    // 고객 이메일 자동 수집
    billing_address_collection: 'auto',
  })

  if (!session.url) {
    throw new Error('Checkout session URL is missing')
  }

  redirect(session.url)
}

app/components/BuyButton.tsx
'use client'

import { createCheckoutSession } from '@/app/actions/checkout'

export function BuyButton({ priceId }: { priceId: string }) {
  return (
    <form action={createCheckoutSession.bind(null, priceId)}>
      <button
        type="submit"
        className="px-6 py-3 bg-indigo-600 text-white rounded-lg hover:bg-indigo-700"
      >
        구매하기
      </button>
    </form>
  )
}

app/api/webhook/route.ts — Webhook 처리
import { NextRequest, NextResponse } from 'next/server'
import { headers } from 'next/headers'
import { stripe } from '@/lib/stripe'
import type Stripe from 'stripe'

export async function POST(req: NextRequest) {
  const body = await req.text()
  const headersList = await headers()
  const signature = headersList.get('stripe-signature')

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

  let event: Stripe.Event

  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    )
  } catch (err) {
    console.error('Webhook signature verification failed:', err)
    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 })
  }

  // 이벤트 타입별 처리
  switch (event.type) {
    case 'checkout.session.completed': {
      const session = event.data.object as Stripe.Checkout.Session
      await handleCompletedCheckout(session)
      break
    }
    case 'payment_intent.payment_failed': {
      const paymentIntent = event.data.object as Stripe.PaymentIntent
      console.error('Payment failed:', paymentIntent.id)
      break
    }
    default:
      // 처리하지 않는 이벤트는 무시
      break
  }

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

async function handleCompletedCheckout(session: Stripe.Checkout.Session) {
  // 실제 구현: DB에 주문 저장, 이메일 발송 등
  console.log('결제 완료:', session.id, session.customer_email)
}

app/actions/subscription.ts — 구독 세션 생성
'use server'

import { redirect } from 'next/navigation'
import { stripe } from '@/lib/stripe'
import { auth } from '@/lib/auth' // 자체 인증 시스템

const PLAN_PRICE_IDS = {
  pro: 'price_1234567890abcdef',         // 월 $29
  enterprise: 'price_abcdef1234567890',  // 월 $99
} as const

type Plan = keyof typeof PLAN_PRICE_IDS

export async function createSubscriptionSession(plan: Plan) {
  const session = await auth()
  if (!session?.user) redirect('/login')

  const checkoutSession = await stripe.checkout.sessions.create({
    mode: 'subscription',
    line_items: [
      {
        price: PLAN_PRICE_IDS[plan],
        quantity: 1,
      },
    ],
    customer_email: session.user.email ?? undefined,
    // 구독 취소/갱신 시 Portal로 연결
    subscription_data: {
      metadata: {
        userId: session.user.id,
      },
    },
    success_url: `${process.env.NEXT_PUBLIC_BASE_URL}/dashboard?subscribed=true`,
    cancel_url: `${process.env.NEXT_PUBLIC_BASE_URL}/pricing`,
  })

  if (!checkoutSession.url) {
    throw new Error('Failed to create checkout session')
  }

  redirect(checkoutSession.url)
}

app/actions/portal.ts — 고객 포털 세션 생성
'use server'

import { redirect } from 'next/navigation'
import { stripe } from '@/lib/stripe'
import { auth } from '@/lib/auth'
import { db } from '@/lib/db' // 자체 DB 클라이언트

export async function openCustomerPortal() {
  const session = await auth()
  if (!session?.user) redirect('/login')

  // DB에 저장된 Stripe Customer ID를 조회
  const user = await db.user.findUnique({
    where: { id: session.user.id },
    select: { stripeCustomerId: true },
  })

  if (!user?.stripeCustomerId) {
    redirect('/pricing') // 아직 구독이 없으면 pricing 페이지로
  }

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

  redirect(portalSession.url)
}