Stripe 완벽 가이드 | 결제 연동·Checkout·Webhook·구독·실전 활용

이 글의 핵심

Stripe로 결제 시스템을 구축하는 완벽 가이드입니다. Checkout Session, Payment Intent, Webhook, 구독 결제까지 실전 예제로 정리했습니다.

실무 경험 공유: 자체 결제 시스템을 Stripe로 전환하면서, 개발 시간이 80% 단축되고 결제 성공률이 15% 향상된 경험을 공유합니다.

들어가며: “결제 구현이 어려워요”

실무 문제 시나리오

시나리오 1: 보안이 걱정돼요

카드 정보를 직접 다루기 위험합니다. Stripe는 PCI DSS 인증을 제공합니다. 시나리오 2: 다양한 결제 수단이 필요해요

각각 연동이 복잡합니다. Stripe는 통합 API를 제공합니다. 시나리오 3: 구독 결제가 필요해요

처음부터 구현하기 어렵습니다. Stripe는 구독 시스템을 제공합니다.

1. Stripe란?

핵심 특징

Stripe는 온라인 결제 플랫폼입니다. 주요 기능:

• Checkout: 호스팅된 결제 페이지
• Payment Intent: 커스텀 결제 플로우
• Webhook: 이벤트 알림
• Subscription: 구독 결제
• 다양한 결제 수단: 카드, Apple Pay, Google Pay

---

2. 설치 및 설정

설치

Stripe를 사용하기 위해 두 개의 패키지가 필요합니다:

• stripe: 서버 측에서 Stripe API를 호출하는 Node.js SDK
• @stripe/stripe-js: 클라이언트 측에서 결제 UI를 렌더링하는 JavaScript 라이브러리

npm install stripe @stripe/stripe-js

환경 변수

Stripe 대시보드에서 발급받은 키를 .env 파일에 설정합니다:

# 서버 측에서 사용 (비공개 키, 절대 클라이언트에 노출 금지)
STRIPE_SECRET_KEY=sk_test_...

# 클라이언트 측에서 사용 (공개 키, 브라우저에 노출 가능)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

# Webhook 검증용 시크릿 (Stripe CLI 또는 대시보드에서 발급)
STRIPE_WEBHOOK_SECRET=whsec_...

주의사항:

• SECRET_KEY는 절대 클라이언트에 노출하면 안 됩니다
• 테스트 환경에서는 sk_test_, 프로덕션에서는 sk_live_로 시작하는 키를 사용합니다

서버 초기화

서버 측에서 재사용할 Stripe 클라이언트 인스턴스를 생성합니다:

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

// Stripe 클라이언트 초기화
// - SECRET_KEY: 서버 전용 비밀 키
// - apiVersion: Stripe API 버전 고정 (호환성 보장)
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2023-10-16', // API 버전을 명시하여 향후 변경에 대응
});

왜 API 버전을 명시하나요? Stripe는 API를 계속 업데이트하지만, 버전을 명시하면 예상치 못한 변경으로부터 안전합니다.

3. Checkout Session

Checkout Session은 Stripe에서 호스팅하는 결제 페이지를 사용하는 가장 간단한 방법입니다.

장점:

• 결제 UI를 직접 구현할 필요 없음
• PCI DSS 규정 준수가 자동으로 처리됨
• 다양한 결제 수단 자동 지원
• 보안이 검증된 환경

서버 (API Route)

서버에서 Checkout Session을 생성하고, 클라이언트가 리디렉트할 URL을 반환합니다:

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

export async function POST(req: Request) {
  // 1. 클라이언트로부터 가격 ID 받기
  const { priceId } = await req.json();
  
  // 2. Stripe Checkout Session 생성
  const session = await stripe.checkout.sessions.create({
    // 결제 모드: 'payment'(일회성), 'subscription'(구독), 'setup'(카드 등록)
    mode: 'payment',
    
    // 구매할 상품 목록
    line_items: [
      {
        price: priceId,    // Stripe Dashboard에서 생성한 Price ID
        quantity: 1,       // 수량
      },
    ],
    
    // 결제 성공 시 리디렉트 URL
    // {CHECKOUT_SESSION_ID}는 Stripe가 자동으로 실제 세션 ID로 치환
    success_url: `${req.headers.get('origin')}/success?session_id={CHECKOUT_SESSION_ID}`,
    
    // 결제 취소 시 리디렉트 URL
    cancel_url: `${req.headers.get('origin')}/cancel`,
  });
  
  // 3. 클라이언트에게 Checkout URL 반환
  return NextResponse.json({ url: session.url });
}

핵심 포인트:

• priceId는 Stripe Dashboard에서 미리 생성한 상품 가격 ID입니다
• success_url과 cancel_url은 결제 후 사용자가 돌아올 페이지입니다
• 실제 결제 페이지는 Stripe 도메인(checkout.stripe.com)에서 호스팅됩니다

클라이언트

버튼 클릭 시 서버 API를 호출하고 Checkout 페이지로 리디렉트합니다:

// components/CheckoutButton.tsx
'use client';

export default function CheckoutButton({ priceId }: { priceId: string }) {
  const handleCheckout = async () => {
    // 1. 서버 API 호출하여 Checkout Session 생성
    const response = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ priceId }),  // 구매할 상품의 가격 ID 전달
    });
    
    // 2. Checkout URL 받기
    const { url } = await response.json();
    
    // 3. Stripe Checkout 페이지로 리디렉트
    window.location.href = url;
  };
  
  return <button onClick={handleCheckout}>결제하기</button>;
}

사용 예시:

// 페이지에서 사용
<CheckoutButton priceId="price_1234567890abcdef" />

흐름 요약:

1. 사용자가 “결제하기” 버튼 클릭
2. 서버에서 Checkout Session 생성
3. Stripe 결제 페이지로 리디렉트
4. 결제 완료 후 success_url로 돌아옴

---

4. Payment Intent

Payment Intent는 커스텀 결제 UI를 구축할 때 사용합니다. Checkout Session과 달리 자체 페이지에서 결제를 처리할 수 있습니다.

언제 사용하나요?

• 결제 UI를 직접 디자인하고 싶을 때
• 복잡한 결제 플로우가 필요할 때
• 결제 과정을 세밀하게 제어하고 싶을 때

서버

Payment Intent를 생성하고 클라이언트에게 clientSecret을 반환합니다:

// app/api/payment-intent/route.ts
export async function POST(req: Request) {
  // 1. 결제 금액 받기
  const { amount } = await req.json();
  
  // 2. Payment Intent 생성
  const paymentIntent = await stripe.paymentIntents.create({
    // 금액을 센트 단위로 변환 (Stripe는 항상 최소 단위 사용)
    // 예: $50.00 = 5000 cents
    amount: amount * 100,
    
    // 통화 코드 (ISO 4217)
    currency: 'usd',  // 'krw', 'jpy', 'eur' 등
    
    // 자동 결제 수단 활성화
    // 카드, Apple Pay, Google Pay 등을 자동으로 표시
    automatic_payment_methods: {
      enabled: true,
    },
  });
  
  // 3. 클라이언트 시크릿 반환
  // 이 값으로 클라이언트에서 결제를 완료할 수 있습니다
  return NextResponse.json({ clientSecret: paymentIntent.client_secret });
}

주요 옵션:

• amount: 센트 단위 금액 (1달러 = 100센트)
• currency: 통화 코드 (한국 원화는 krw)
• automatic_payment_methods: 사용 가능한 모든 결제 수단 자동 활성화

클라이언트

Stripe Elements를 사용하여 결제 UI를 렌더링하고 결제를 처리합니다:

'use client';
import { loadStripe } from '@stripe/stripe-js';
import { Elements, PaymentElement, useStripe, useElements } from '@stripe/react-stripe-js';
import { useState, useEffect } from 'react';

// Stripe.js 로드 (앱 전체에서 한 번만 실행)
const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!);

// 실제 결제 폼 컴포넌트
function CheckoutForm() {
  // Stripe Hooks
  const stripe = useStripe();      // Stripe 인스턴스
  const elements = useElements();  // 결제 요소 관리
  const [message, setMessage] = useState('');
  
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    
    // Stripe와 Elements가 로드될 때까지 대기
    if (!stripe || !elements) return;
    
    // 결제 확인 요청
    const { error } = await stripe.confirmPayment({
      elements,  // 결제 폼 요소
      confirmParams: {
        // 결제 성공 시 리디렉트할 URL
        return_url: `${window.location.origin}/success`,
      },
    });
    
    // 에러 처리 (리디렉트되지 않은 경우)
    if (error) {
      setMessage(error.message || '결제 중 오류가 발생했습니다');
    }
  };
  
  return (
    <form onSubmit={handleSubmit}>
      {/* Stripe가 제공하는 결제 UI 컴포넌트 */}
      <PaymentElement />
      
      <button type="submit" disabled={!stripe}>
        결제하기
      </button>
      
      {/* 에러 메시지 표시 */}
      {message && <div className="error">{message}</div>}
    </form>
  );
}

// 메인 Checkout 페이지 컴포넌트
export default function CheckoutPage() {
  const [clientSecret, setClientSecret] = useState('');
  
  // 컴포넌트 마운트 시 Payment Intent 생성
  useEffect(() => {
    fetch('/api/payment-intent', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ amount: 50 }),  // $50.00
    })
      .then((res) => res.json())
      .then((data) => setClientSecret(data.clientSecret));
  }, []);
  
  return (
    <div>
      {/* clientSecret이 있을 때만 결제 폼 렌더링 */}
      {clientSecret && (
        <Elements 
          stripe={stripePromise} 
          options={{ clientSecret }}  // Payment Intent 연결
        >
          <CheckoutForm />
        </Elements>
      )}
    </div>
  );
}

컴포넌트 구조 설명:

1. CheckoutPage:

   • Payment Intent를 생성하고 clientSecret을 받아옴
   • <Elements> Provider로 Stripe 컨텍스트 제공

2. CheckoutForm:

   • <PaymentElement>: Stripe가 제공하는 결제 UI (카드 입력 필드 등)
   • confirmPayment(): 결제 실행 및 확인
   • 결제 성공 시 자동으로 return_url로 리디렉트

주요 Hook:

• useStripe(): Stripe 인스턴스 접근
• useElements(): 결제 요소 제어

흐름:

1. 페이지 로드 → Payment Intent 생성
2. clientSecret 받음 → Elements 렌더링
3. 사용자가 카드 정보 입력
4. 제출 → confirmPayment() 실행
5. 성공 → /success로 리디렉트

---

5. Payment Intent 상태 머신과 SCA(강력 고객 인증)

Payment Intent는 단순한 “성공/실패” 플래그가 아니라, 카드 네트워크·발급사·규제(PSD2 등)와의 상호작용을 반영하는 상태 기반 객체입니다. 운영·디버깅·장애 대응을 하려면 어떤 상태가 언제 발생하는지를 먼저 그림으로 잡는 것이 안전합니다.

5.1 상태 머신(핵심 전이)

Stripe가 문서화하는 status 값은 대표적으로 다음과 같습니다(결제 수단·캡처 모델에 따라 일부는 등장하지 않을 수 있음).

상태	의미(요약)
requires_payment_method	결제 수단이 없거나 거절되어 다른 수단이 필요함
requires_confirmation	confirmation_method 등 설정에 따라 서버에서 한 번 더 확정이 필요할 수 있음
requires_action	SCA(3DS 등) 같은 추가 인증이 필요함(next_action 확인)
processing	승인·정산이 비동기로 진행 중
requires_capture	수동 캡처 모델에서 인증은 끝났으나 청구 확정(캡처) 전
canceled	만료·취소 등으로 종료
succeeded	자금 이동이 확정된 성공 종료(캡처 모델에 맞는 의미)

아래는 이해를 돕기 위한 개념적 상태 다이어그램입니다(실제 전이는 capture_method, confirmation_method, 결제 수단에 따라 달라짐).

stateDiagram-v2
  [*] --> requires_payment_method
  requires_payment_method --> requires_confirmation: 결제수단 확정
  requires_payment_method --> requires_action: SCA 필요
  requires_confirmation --> requires_action: SCA 필요
  requires_action --> processing: 인증 완료
  requires_confirmation --> processing: 즉시 승인 경로
  processing --> requires_capture: 수동 캡처
  processing --> succeeded: 자동 캡처/즉시 완료
  requires_capture --> succeeded: capture 호출
  requires_payment_method --> canceled: 실패/만료
  requires_action --> canceled: 중단/만료
  processing --> canceled: 취소

왜 “상태”가 중요한가요?
클라이언트에서 confirmPayment가 끝났다고 해서 곧바로 succeeded만 오는 것은 아닙니다. 특히 유럽 카드·특정 리스크 프로필에서는 requires_action으로 빠졌다가 인증 후 processing을 거쳐 성공합니다. 따라서 주문 확정(재고 차감·라이선스 발급)은 “프론트 성공 화면”이 아니라 Webhook + 서버 측 조회로 맞추는 것이 정석입니다.

5.2 SCA 플로우(3D Secure / next_action)

SCA(Strong Customer Authentication)는 “카드 번호 + CVC”만으로는 부족할 때, 발급사가 추가 인증(OTP, 앱 승인, 생체 등)을 요구하는 절차입니다. Stripe에서는 이 단계가 requires_action 상태와 payment_intent.next_action으로 표현됩니다.

전형적인 흐름은 다음과 같습니다.

1. 서버가 PaymentIntent를 생성하고 client_secret을 클라이언트에 전달합니다.
2. 사용자가 결제를 시도하면 Stripe.js가 카드사·네트워크와 협상하고, SCA가 필요하면 Intent가 requires_action이 됩니다.
3. Stripe.js(confirmPayment 등)가 3DS 챌린지 UI를 완료하면, Intent는 processing 등으로 이동한 뒤 최종적으로 성공·실패가 결정됩니다.
4. 서버는 payment_intent.succeeded(또는 실패 이벤트) Webhook과, 필요 시 paymentIntents.retrieve로 최종 상태를 재확인합니다.

구현 시 자주 하는 실수는 다음과 같습니다.

• requires_action을 에러로만 처리하고 재시도 루프에 빠지는 경우 — 이는 정상 단계일 수 있습니다.
• 테스트 카드만으로 “항상 즉시 성공”을 가정하고, 운영에서 3DS가 켜졌을 때 UX가 깨지는 경우 — 로딩·안내 문구·모바일 WebView 대응이 필요합니다.
• 클라이언트 성공 URL만 믿고 풀필먼트하는 경우 — 반드시 Webhook 또는 서버 확정 경로를 두세요.

운영 팁: 대시보드에서 테스트할 때는 “3DS 인증이 필요한” 테스트 카드 시나리오를 의도적으로 돌려보고, payment_intent.requires_action 직후의 UI 상태(스피너, 안내)를 점검하십시오.

---

6. Webhook

Webhook은 Stripe에서 결제 이벤트가 발생할 때 서버로 알림을 보내는 메커니즘입니다.

왜 필요한가요?

• 결제가 완료되었을 때 주문을 처리하거나
• 구독이 갱신되었을 때 서비스 연장하거나
• 결제 실패 시 사용자에게 알림을 보내는 등

사용자가 결제 페이지를 떠나더라도 서버는 Webhook을 통해 결제 상태를 정확히 파악할 수 있습니다.

서버

Webhook 엔드포인트를 구현하여 Stripe 이벤트를 처리합니다:

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

export async function POST(req: Request) {
  // 1. 요청 본문과 서명 헤더 가져오기
  const body = await req.text();  // Raw body (JSON 파싱 전)
  const signature = headers().get('stripe-signature')!;
  
  let event;
  
  try {
    // 2. Webhook 이벤트 검증 및 구성
    // 이 과정에서 요청이 실제로 Stripe에서 왔는지 확인합니다
    event = stripe.webhooks.constructEvent(
      body,                                    // 요청 본문
      signature,                               // Stripe 서명
      process.env.STRIPE_WEBHOOK_SECRET!      // Webhook 시크릿
    );
  } catch (err) {
    // 검증 실패 시 400 에러 반환
    console.error('Webhook signature verification failed:', err.message);
    return new Response(`Webhook Error: ${err.message}`, { status: 400 });
  }
  
  // 3. 이벤트 타입별 처리
  switch (event.type) {
    // Checkout Session이 완료되었을 때
    case 'checkout.session.completed':
      const session = event.data.object;
      console.log('결제 성공:', session.id);
      
      // 주문 처리 로직 실행
      // 예: 데이터베이스에 주문 기록, 이메일 발송 등
      await fulfillOrder(session);
      break;
    
    // Payment Intent가 성공했을 때
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      console.log('PaymentIntent 성공:', paymentIntent.id);
      // 결제 성공 처리
      break;
    
    // 결제가 실패했을 때
    case 'payment_intent.payment_failed':
      const failedPayment = event.data.object;
      console.log('결제 실패:', failedPayment.id);
      // 실패 알림, 재시도 안내 등
      break;
    
    // 구독 관련 이벤트
    case 'customer.subscription.created':
      // 구독 생성 처리
      break;
    case 'customer.subscription.deleted':
      // 구독 취소 처리
      break;
  }
  
  // 4. Stripe에 성공 응답 반환 (200 OK)
  return new Response(JSON.stringify({ received: true }));
}

// 주문 처리 예시 함수
async function fulfillOrder(session: any) {
  // 데이터베이스에 주문 저장
  // 이메일 발송
  // 재고 업데이트 등
  console.log('주문 처리 중...', session.id);
}

핵심 포인트:

1. 서명 검증: constructEvent()로 요청이 Stripe에서 왔는지 반드시 확인
2. Raw Body: Webhook은 raw body를 사용해야 서명 검증이 가능
3. 멱등성: 같은 이벤트가 여러 번 올 수 있으니 중복 처리 방지 필요

6.1 Webhook 서명 검증의 내부 동작(HMAC-SHA256)

Stripe Webhook은 HTTP 본문이 변조되지 않았는지와 Stripe가 보낸 요청인지를 동시에 보장하기 위해, 요청 헤더 Stripe-Signature를 함께 보냅니다. Node SDK의 constructEvent(rawBody, signature, secret)은 대략 다음을 수행합니다.

1. Stripe-Signature 파싱

   • 일반적으로 t=<unix_timestamp>와 v1=<hex_signature> 형태의 토큰이 쉼표로 구분되어 여러 개 올 수 있습니다(버전 롤링·재전송 대비).

2. 서명 대상 문자열 구성

   • 메시지는 보통 ${timestamp}.${rawBody}처럼 타임스탬프와 원문 바디를 점(.)으로 이은 문자열입니다.
   • 여기서 rawBody는 JSON 파싱 전 문자열이어야 합니다. 프레임워크가 먼저 JSON으로 파싱해 다시 직렬화하면 공백·키 순서가 바뀌어 서명이 깨집니다.

3. HMAC-SHA256

   • 대시보드/CLI에서 발급한 whsec_... 시크릿을 재료로, 위 메시지에 대해 HMAC-SHA256을 계산합니다.
   • 수신한 v1 서명과 타이밍 안전 비교(constant-time compare)로 일치 여부를 판별합니다.

4. 재전송·리플레이 방지(타임스탬프 tolerance)

   • 너무 오래된 t는 거부하여 옛날 요청을 재주입하는 공격을 완화합니다. SDK는 보통 수 분 단위 허용 오차를 둡니다(환경/SDK에 따름).

즉, Webhook 보안의 핵심은 “비밀을 아는가?”가 아니라 “타임스탬프+원문에 대해 같은 HMAC을 만들 수 있는가?”입니다. 프록시가 본문을 수정하거나, 로드밸런서가 gzip을 잘못 다루거나, Next.js에서 req.json()으로 먼저 읽으면 같은 시크릿을 알아도 검증이 실패합니다.

운영에서 자주 보는 실패 원인

• Vercel/프록시에서 body를 변형 — 반드시 raw 스트림으로 읽기
• 멀티 리전에서 시크릿이 다른 엔드포인트와 섞임 — 엔드포인트별 whsec 분리 관리
• 테스트 CLI stripe listen의 시크릿과 프로덕션 대시보드 시크릿 혼동

수동으로 검증 로직을 구현할 필요는 거의 없고, 공식 SDK의 constructEvent를 쓰는 것이 가장 안전합니다. 다만 장애 분석을 위해서는 위 구조를 알아두는 것이 큰 도움이 됩니다.

Webhook 등록

로컬 개발 환경:

# Stripe CLI 설치 후 실행
# Stripe 이벤트를 로컬 서버로 전달합니다
stripe listen --forward-to localhost:3000/api/webhook

# 출력되는 webhook secret을 .env에 저장
# whsec_xxx... 형태

프로덕션 환경:

1. Stripe Dashboard → Webhooks 메뉴
2. “Add endpoint” 클릭
3. 엔드포인트 URL 입력: https://yourdomain.com/api/webhook
4. 수신할 이벤트 선택:
   • checkout.session.completed
   • payment_intent.succeeded
   • payment_intent.payment_failed
   • customer.subscription.* (구독 사용 시)
5. Webhook 시크릿 복사하여 .env에 저장

테스트:

# 테스트 이벤트 전송
stripe trigger payment_intent.succeeded

주의사항:

• Webhook 엔드포인트는 반드시 HTTPS여야 합니다 (로컬 제외)
• 응답은 10초 이내에 반환해야 합니다
• 오래 걸리는 작업은 백그라운드 큐에서 처리하세요

---

7. 멱등성 키(Idempotency-Key) 메커니즘

Stripe API는 네트워크 타임아웃·재시도·클라이언트 중복 클릭이 흔하기 때문에, 같은 의도의 요청이 두 번 도착해도 한 번만 적용되도록 HTTP 수준의 멱등성을 제공합니다.

7.1 동작 원리(개념)

• 클라이언트(보통 서버)가 POST 요청 시 헤더에 Idempotency-Key: <임의의 고유 문자열>을 붙입니다.
• Stripe는 이 키를 일정 기간(통상 24시간) 동안 기억하고, 같은 키 + 같은 연산에 대해 같은 응답을 돌려줍니다.
• 같은 키인데 본문이 다르면 충돌로 에러가 나는 것이 정상입니다(“같은 주문을 두 가지 금액으로” 재시도하는 실수 방지).

7.2 왜 서버에서 생성해야 하나요?

• 브라우저가 만든 키는 새로고침·탭 중복으로 쉽게 어긋납니다.
• 결제 생성·캡처·환불처럼 금전에 영향을 주는 연산은 서버가 요청 단위로 키를 발급하고, DB의 orderId, requestId, ULID 등과 1:1로 매핑하는 패턴이 안전합니다.

7.3 Node(Stripe SDK) 예시

SDK는 대부분의 쓰기 API에서 idempotencyKey 옵션을 받습니다.

// 동일한 주문 확정 요청이 재시도되어도 이중 청구를 막고 싶을 때
await stripe.paymentIntents.create(
  {
    amount: 5000,
    currency: 'krw',
    automatic_payment_methods: { enabled: true },
  },
  {
    idempotencyKey: `order_${orderId}_pi_create`, // 서버가 결정한 안정적 키
  }
);

주의: 멱등성은 Stripe 측 중복 방지입니다. 애플리케이션 DB에서 주문 상태 업데이트도 멱등하게 만들려면, Webhook 핸들러에서 event.id 또는 비즈니스 키로 중복 처리 방지를 함께 구현해야 합니다(아래 9. 프로덕션 결제 운영 패턴 절 참고).

---

8. 구독 결제

구독(Subscription)은 정기 결제를 자동으로 처리합니다. SaaS, 멤버십, 구독 서비스에 필수적입니다.

상품 및 가격 생성

먼저 Stripe Dashboard 또는 API로 상품과 가격을 생성합니다:

// 1. 상품(Product) 생성
const product = await stripe.products.create({
  name: 'Premium Plan',           // 상품명
  description: '프리미엄 플랜. Stripe 완벽 가이드에 대한 완전한 가이드입니다. 실전 예제와 함께 핵심 개념부터 고급 활용까지 다룹니다.',    // 설명 (선택)
  // images: ['https://...'],     // 상품 이미지 (선택)
});

// 2. 가격(Price) 생성
const price = await stripe.prices.create({
  product: product.id,             // 위에서 생성한 상품 ID
  unit_amount: 1999,               // $19.99 (센트 단위)
  currency: 'usd',                 // 통화
  recurring: {
    interval: 'month',             // 결제 주기: 'day', 'week', 'month', 'year'
    interval_count: 1,             // 몇 개월마다? (선택, 기본값 1)
  },
  // trial_period_days: 14,        // 무료 체험 기간 (선택)
});

console.log('생성된 Price ID:', price.id);  // 이 ID를 Checkout에서 사용

실무 팁:

• 대부분의 경우 Stripe Dashboard에서 미리 생성하는 것이 편리합니다
• 생성된 Price ID를 데이터베이스나 환경 변수에 저장하세요

구독 Checkout

구독 결제는 mode: 'subscription'만 바꾸면 됩니다:

// app/api/subscribe/route.ts
export async function POST(req: Request) {
  const { priceId, customerId } = await req.json();
  
  const session = await stripe.checkout.sessions.create({
    // 구독 모드로 설정
    mode: 'subscription',
    
    // 구독할 플랜
    line_items: [
      {
        price: priceId,  // 미리 생성한 구독 가격 ID
        quantity: 1,
      },
    ],
    
    // 기존 고객 ID (선택)
    // customer: customerId,
    
    // 결제 완료 URL
    success_url: `${origin}/success?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${origin}/cancel`,
    
    // 구독 관련 추가 옵션
    subscription_data: {
      // trial_period_days: 14,  // 무료 체험
      // metadata: {             // 메타데이터
      //   userId: '123',
      // },
    },
  });
  
  return NextResponse.json({ url: session.url });
}

일회성 결제 vs 구독 결제:

• 일회성: mode: 'payment'
• 구독: mode: 'subscription'
• 나머지는 거의 동일!

구독 관리

고객의 구독을 관리하는 API들:

// 1. 구독 취소
await stripe.subscriptions.cancel('sub_xxx');

// 2. 구독 즉시 취소 (환불 없음)
await stripe.subscriptions.cancel('sub_xxx', {
  prorate: false,  // 비례 계산 안 함
});

// 3. 구독 기간 종료 시 취소 (사용자가 구독 기간 끝까지 사용)
await stripe.subscriptions.update('sub_xxx', {
  cancel_at_period_end: true,  // 현재 구독 기간 종료 시 취소
});

// 4. 구독 플랜 변경 (업그레이드/다운그레이드)
await stripe.subscriptions.update('sub_xxx', {
  items: [
    {
      id: 'si_xxx',           // 기존 구독 항목 ID
      price: 'price_new',     // 새 가격 ID
    },
  ],
  proration_behavior: 'create_prorations',  // 비례 계산 청구
});

// 5. 구독 재개 (취소 예정 구독을 다시 활성화)
await stripe.subscriptions.update('sub_xxx', {
  cancel_at_period_end: false,
});

// 6. 구독 정보 조회
const subscription = await stripe.subscriptions.retrieve('sub_xxx');
console.log('구독 상태:', subscription.status);
// 가능한 상태: 'active', 'past_due', 'canceled', 'incomplete' 등

고객 포털 (Customer Portal)

Stripe가 제공하는 구독 관리 페이지를 사용하면 고객이 직접 구독을 관리할 수 있습니다:

// 고객 포털 세션 생성
const session = await stripe.billingPortal.sessions.create({
  customer: 'cus_xxx',  // Stripe 고객 ID
  return_url: `${origin}/account`,  // 포털 종료 후 돌아갈 URL
});

// 클라이언트에서 포털로 리디렉트
window.location.href = session.url;

고객 포털 기능:

• 결제 수단 변경
• 구독 플랜 변경
• 구독 취소
• 청구 내역 확인

설정 방법: Stripe Dashboard → Settings → Billing → Customer portal 에서 활성화

9. 프로덕션 결제 운영 패턴

실서비스에서 결제는 “API가 통과했다”로 끝나지 않고, 관측·재시도·정합성·규정이 묶입니다. 아래는 Stripe를 쓸 때 특히 자주 쓰는 운영 패턴입니다.

9.1 단일 진실 원천: Webhook + 서버 확정

• 클라이언트 성공 페이지는 UX용이며, 재고·구독 활성화·권한 부여는 checkout.session.completed, payment_intent.succeeded, invoice.paid 등 서버가 신뢰하는 이벤트로 처리합니다.
• 사용자가 브라우저를 닫아도 Webhook은 올 수 있어야 하므로, 비동기 큐와 재시도 가능한 핸들러를 전제로 설계합니다.

9.2 Webhook 멱등 처리(이벤트 중복)

Stripe는 동일 이벤트가 여러 번 전달될 수 있습니다. 핸들러는 항상 멱등해야 합니다.

• DB에 stripe_event_id 유니크 인덱스를 두고, 처리 시작 시 INSERT로 “처리 선점”을 합니다.
• 이미 존재하면 조용히 200 OK로 종료합니다.
• 처리 중 예외가 나면 Stripe가 재시도하므로, 부분 성공 상태를 남기지 않도록 트랜잭션 경계를 신중히 잡습니다.

9.3 아웃박스(Outbox) 패턴

Webhook 핸들러에서 이메일·ERP·외부 API까지 동기로 모두 호출하면 10초 제한·타임아웃에 취약합니다.

• Webhook에서는 “주문 확정됨”만 DB에 기록하고,
• 별도 워커가 큐를 소비해 비동기 후속 작업을 수행합니다.
• 이렇게 하면 재시도·데드레터 큐·모니터링을 붙이기 쉽습니다.

9.4 금액·통화·환율

• 금액은 항상 최소 화폐 단위(정수)로 다루고, 부동소수점을 쓰지 않습니다.
• 표시용 통화와 청구 통화가 다를 수 있으면, 사용자에게 보여준 금액과 Stripe에 전달한 금액을 로그로 남겨 분쟁 대응에 대비합니다.

9.5 카드 거절·SCA 재시도

• card_declined, insufficient_funds, authentication_required 등 거절 코드는 사용자 메시지·재시도 UX를 다르게 가져가는 것이 좋습니다.
• SCA가 필요한 경우는 requires_action 흐름을 완료해야 하므로, “결제 실패”와 “인증 대기”를 UI에서 구분합니다.

9.6 대사(Reconciliation)와 모니터링

• 주기적으로 Stripe 대시보드·Balance transaction·내부 주문 DB를 대조합니다.
• 메트릭 예: Webhook 실패율, payment_intent.payment_failed 비율, 평균 확정 지연, 재시도 큐 적체량.

9.7 보안·규정

• 서버 키는 절대 클라이언트에 노출하지 않습니다.
• 로그에 PAN 전체, CVC, client_secret을 남기지 않습니다.
• GDPR·전자상거래 등 개인정보·청약철회 정책과 결제 데이터 보관 기간을 맞춥니다.

---

정리 및 체크리스트

핵심 요약

• Stripe: 온라인 결제 플랫폼
• Checkout: 호스팅된 결제 페이지
• Payment Intent: 커스텀 플로우
• 상태 머신·SCA: requires_action·3DS 등 추가 인증과 최종 확정은 서버/Webhook 기준
• Webhook: 이벤트 알림 + Stripe-Signature HMAC으로 위·변조 방지
• Idempotency-Key: API 재시도 시 이중 청구·이중 환불 방지
• Subscription: 구독 결제
• 프로덕션: Webhook 멱등·아웃박스·대사·관측
• 보안: PCI DSS 인증

구현 체크리스트

• Stripe 계정 생성
• SDK 설치
• Checkout 구현
• Payment Intent·SCA(3DS) 시나리오 테스트
• Webhook 설정(raw body·서명 검증)
• Webhook·결제 생성에 멱등성(이벤트 ID·Idempotency-Key) 적용
• 구독 결제 구현
• 테스트
• 프로덕션 배포(대사·모니터링)

---

같이 보면 좋은 글

• Next.js App Router 가이드
• Supabase 완벽 가이드
• Webhook 완벽 가이드

---

관련 글 (내부 링크)

Stripe와 함께 보면 좋은 백엔드·결제 관련 가이드입니다:

• Supabase 완벽 가이드 | 인증·DB·실시간·스토리지·엣지 함수 - 백엔드 + Stripe 연동
• Next.js App Router 완벽 가이드 | 서버 컴포넌트·스트리밍 - Stripe 결제 UI 구현
• Clerk 완벽 가이드 | 인증·사용자 관리·OAuth·MFA - Stripe + 인증 통합
• Convex 완벽 가이드 | 실시간 백엔드·타입 안전성 - Stripe Webhook 처리
• Railway 완벽 가이드 | Node.js·PostgreSQL·Redis 배포 - Stripe 서버 배포

---

이 글에서 다루는 키워드

Stripe, Payment, Checkout, Webhook, Subscription, Backend, E-commerce

자주 묻는 질문 (FAQ)

Q. 수수료는 얼마인가요?

A. 국내 카드 3.6% + 50원, 해외 카드 4.3% + 50원입니다.

Q. 한국에서 사용할 수 있나요?

A. 네, 한국 사업자도 사용할 수 있습니다.

Q. 테스트는 어떻게 하나요?

A. 테스트 모드에서 테스트 카드 번호를 사용하면 됩니다.

Q. 프로덕션에서 사용해도 되나요?

A. 네, 전 세계 수백만 기업이 사용하는 안정적인 플랫폼입니다.

Q. requires_action이 뜨면 결제가 실패한 건가요?

A. 반드시 그렇지는 않습니다. SCA(3D Secure 등) 가 필요할 때 나타나는 정상 단계인 경우가 많으며, Stripe.js로 인증을 마치면 이어서 승인·실패가 결정됩니다. 최종 비즈니스 로직은 Webhook·서버 조회로 확정하십시오.

Q. 같은 Idempotency-Key로 다른 금액을 보내면 어떻게 되나요?

A. Stripe는 이를 충돌로 처리하여 에러를 반환합니다. 키는 “같은 의도의 동일 요청”에만 재사용해야 하며, 금액이 바뀌면 새 키를 발급하는 것이 맞습니다.

심화 부록: 구현·운영 관점

이 부록은 앞선 본문에서 다룬 주제(「Stripe 완벽 가이드 | 결제 연동·Checkout·Webhook·구독·실전 활용」)를 구현·런타임·운영 관점에서 다시 압축합니다. 도메인별 세부 구현은 글마다 다르지만, 입력 검증 → 핵심 연산 → 부작용(I/O·네트워크·동시성) → 관측의 흐름으로 장애를 나누면 원인 추적이 빨라집니다.

내부 동작과 핵심 메커니즘

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(런타임·게이트웨이·프로세스)
  participant D as 의존성(API·DB·큐·파일)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)

• 불변 조건(Invariant): 버퍼 경계, 프로토콜 상태, 트랜잭션 격리, FD 상한 등 단계별로 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
• 결정성: 순수 층과 시간·네트워크·스케줄에 의존하는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
• 경계 비용: 직렬화, 인코딩, syscall 횟수, 락 경합, 할당·GC, 캐시 미스를 의심 목록에 둡니다.
• 백프레셔: 생산자가 소비자보다 빠를 때 버퍼·큐·스트림에서 속도를 줄이는 신호를 어디에 둘지 정의합니다.

프로덕션 운영 패턴

영역	운영 관점 질문
관측성	요청 단위 상관 ID, 에러율·지연 p95/p99, 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성	입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능	캐시·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리/블루그린, 마이그레이션·피처 플래그가 문서화되어 있는가
용량	피크 트래픽·디스크·FD·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 프로덕션에 가깝게 맞출수록 재현율이 올라갑니다.

확장 예시: 엔드투엔드 미니 시나리오

앞선 본문 주제(「Stripe 완벽 가이드 | 결제 연동·Checkout·Webhook·구독·실전 활용」)를 배포·운영 흐름에 맞춰 옮긴 체크리스트입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

1. 입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드를 경계에 둔다.
2. 핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 로그·메트릭·트레이스에서 한 흐름으로 본다.
3. 실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
4. 호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지 확인한다.
5. 부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값을 점검한다.

handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)
  authorize(validated, ctx)
  result = domainCore(validated)
  persistOrEmit(result, idempotentKey)
  recordMetrics(ctx, latency, outcome)
  return result

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스, 타임아웃, 외부 의존성, DNS	최소 재현 스크립트, 분산 트레이스·로그 상관관계, 재시도·서킷 설정 점검
성능 저하	N+1, 동기 I/O, 락 경합, 과도한 직렬화, 캐시 미스	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 구독/리스너 누수, 대용량 버퍼, 커넥션 미반납	상한·TTL·힙/FD 스냅샷 비교
빌드·배포만 실패	환경 변수, 권한, 플랫폼 차이, lockfile	CI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정 불일치	프로필·시크릿·기본값, 리전	스키마 검증된 설정 단일 소스와 배포 매트릭스 표준화
데이터 불일치	비멱등 재시도, 부분 쓰기, 캐시 무효화 누락	멱등 키·아웃박스·트랜잭션 경계 재검토

권장 순서: (1) 최소 재현 (2) 최근 변경 범위 축소 (3) 환경·의존성 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트.

배포 전에는 git add → git commit → git push 후 npm run deploy 순서를 권장합니다.