결제 연동: Stripe Subscription 전체 흐름

Customer:    한 사용자(=tenant) = 1 customer
Product:     상품 (Pro Plan, Business Plan)
Price:       가격 (월/연·금액·통화)
Subscription: customer가 price 구독 중
Invoice:     매달 청구서 (자동 생성)

pnpm add stripe @stripe/stripe-js

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

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


// .env
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

// app/api/checkout/route.ts
import { stripe } from '@/lib/stripe';
import { auth } from '@/lib/auth';

export async function POST(req: Request) {
  const { user } = await auth();
  if (!user) return new Response('Unauthorized', { status: 401 });

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

  // Stripe customer 생성/조회
  let customerId = user.stripeCustomerId;
  if (!customerId) {
    const customer = await stripe.customers.create({
      email: user.email,
      metadata: { userId: user.id, tenantId: user.tenantId },
    });
    customerId = customer.id;
    await db.user.update({
      where: { id: user.id },
      data: { stripeCustomerId: customerId },
    });
  }

  const session = await stripe.checkout.sessions.create({
    customer: customerId,
    mode: 'subscription',
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.APP_URL}/billing?success=true`,
    cancel_url: `${process.env.APP_URL}/billing?canceled=true`,
    allow_promotion_codes: true,
    billing_address_collection: 'auto',
    subscription_data: {
      trial_period_days: 14,  // 14일 무료 체험
      metadata: { tenantId: user.tenantId },
    },
  });

  return Response.json({ url: session.url });
}

'use client';

export function UpgradeButton({ priceId }: { priceId: string }) {
  const handleClick = async () => {
    const res = await fetch('/api/checkout', {
      method: 'POST',
      body: JSON.stringify({ priceId }),
    });
    const { url } = await res.json();
    window.location.href = url;
  };

  return <button onClick={handleClick}>Pro로 업그레이드</button>;
}

// app/api/webhooks/stripe/route.ts
import { stripe } from '@/lib/stripe';
import { headers } from 'next/headers';

export async function POST(req: Request) {
  const body = await req.text();
  const sig = (await headers()).get('stripe-signature')!;

  let event;
  try {
    event = stripe.webhooks.constructEvent(
      body, sig, process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    return new Response('Invalid signature', { status: 400 });
  }

  switch (event.type) {
    case 'customer.subscription.created':
    case 'customer.subscription.updated':
      const sub = event.data.object;
      await db.tenant.update({
        where: { id: sub.metadata.tenantId },
        data: {
          plan: priceIdToPlan(sub.items.data[0].price.id),
          stripeSubscriptionId: sub.id,
          subscriptionStatus: sub.status,
          currentPeriodEnd: new Date(sub.current_period_end * 1000),
        },
      });
      break;

    case 'customer.subscription.deleted':
      await db.tenant.update({
        where: { stripeSubscriptionId: event.data.object.id },
        data: { plan: 'free', subscriptionStatus: 'canceled' },
      });
      break;

    case 'invoice.payment_failed':
      // 이메일 알림 + UI에 결제 실패 배너
      await emailQueue.add('payment_failed', {
        customerId: event.data.object.customer,
      });
      break;
  }

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


// Next.js — body raw 보장
export const runtime = 'nodejs';
export const preferredRegion = 'icn1';

// app/api/billing/portal/route.ts
export async function POST(req: Request) {
  const { user } = await auth();
  if (!user?.stripeCustomerId) {
    return new Response('No subscription', { status: 400 });
  }

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

  return Response.json({ url: session.url });
}


// → 사용자가 플랜 변경, 결제수단 변경, 구독 해지 모두
// → Stripe가 호스팅하는 표준 UI
// → 별도 UI 개발 불필요

사용자가 월중 Pro($20) → Business($50) 변경:
- 남은 일수: 15일
- Pro 환불: $20 × 15/30 = $10
- Business 청구: $50 × 15/30 = $25
- 즉시 청구: $25 - $10 = $15


Stripe 자동 처리 — proration_behavior:
- 'create_prorations' (기본): 다음 청구서에 추가
- 'always_invoice': 즉시 청구