Stripe 결제/구독 통합 워크플로우. Stripe MCP 도구로 제품/가격 생성, Checkout Session 구현, Webhook 처리, Billing Portal 연동, 구독 라이프사이클 관리. 'Stripe 설정', '결제 연동', '구독 추가', '웹훅 처리', '가격 생성', '결제 링크', '환불', 'Stripe 제품' 등을 언급하면 이 스킬을 참조할 것. 일반 API CRUD와는 구분됨 — Stripe 관련이 아닌 순수 백엔드 작업은 api-dev 스킬을 사용.
stripe-newsletter 프로젝트의 Stripe 결제/구독 통합 표준 워크플로우.
새 구독 플랜을 추가하거나 기존 플랜을 수정할 때:
mcp__claude_ai_Stripe__create_product(name, description)
mcp__claude_ai_Stripe__create_price(
product: product_id,
unit_amount: 1900, // 센트 단위
currency: "usd",
recurring: { interval: "month" }
)
.env에 가격 ID 추가:
STRIPE_BASIC_PRICE_ID=price_xxx
STRIPE_PREMIUM_PRICE_ID=price_xxx
packages/shared/src/constants/plans.ts의 PLANS 상수를 업데이트.
사용자 → POST /stripe/checkout → Stripe Checkout Session 생성 → 리다이렉트
↓
Stripe Checkout 페이지 → 결제 완료 → success_url 리다이렉트
↓
Webhook: checkout.session.completed → DB에 구독 생성
핵심 코드: apps/api/src/modules/stripe/stripe.service.ts — createCheckoutSession()
metadata에 반드시 userId와 plan을 포함한다. 웹훅에서 이 metadata로 사용자/플랜을 식별.
| 이벤트 | 처리 | DB 변경 |
|---|---|---|
checkout.session.completed | 구독 레코드 생성 | subscription INSERT |
customer.subscription.updated | 상태/기간 동기화 | subscription UPDATE |
customer.subscription.deleted | 취소 처리 | subscription UPDATE (canceled) |
invoice.payment_succeeded | 결제 이력 기록 | payment_history INSERT |
invoice.payment_failed | 실패 기록 + 상태 변경 | payment_history INSERT + subscription UPDATE (past_due) |
webhook_logs 테이블로 stripeEventId 중복 검사:
stripeEventId로 기존 로그 조회{ received: true, duplicate: true } 반환processed: true 업데이트stripe listen --forward-to localhost:4000/stripe/webhook
사용자가 결제 수단 변경, 구독 업그레이드/다운그레이드, 인보이스 조회를 셀프 서비스로 처리:
POST /stripe/portal → Billing Portal Session 생성 → 리다이렉트
incomplete → active → past_due → canceled
↘ canceled
trialing → active
상세 상태 매핑은 references/stripe-states.md 참조.
PLAN_DISPLAY_PRICE 상수 사용 또는 (amount / 100).toFixed(2)