Stripe 결제 추가

초보자 연습

전제 조건: 로컬에서 실행 중인 앱(5분 만에 출시)과 실제 계정용 마이그레이션된 데이터베이스(데이터베이스 설정). Stripe 계정용 이메일 주소가 필요합니다—카드도 결제도 없습니다. 이 가이드의 모든 것은 테스트 모드에서 진행됩니다: 가짜 돈, 테스트 카드 번호, 공개 전 무제한 재시도.

용어 정리: 테스트 모드는 Stripe의 샌드박스입니다—대시보드의 Test mode 토글이 끄기 전까지 모든 키, 제품, 결제를 가짜로 유지합니다. 시크릿 키(sk_test_…)는 Stripe에 대한 서버의 비밀번호입니다. 가격이 있는 제품은 고객이 구매하는 것이고, price id(price_…)가 코드에서 그것을 지명합니다. webhook은 결제 성공이나 구독 변경 시 Stripe가 서버를 호출하는 것이고, 서명 시크릿(whsec_…)은 그 호출이 정말 Stripe에서 온 것임을 증명합니다.

만드는 것: Stripe 계정, 반복 가격의 제품 하나, 시크릿 API 키, webhook 엔드포인트—약 20분. 체크아웃 페이지 자체는 Stripe가 호스팅합니다. 킷은 서버 측에서 세션을 만들고 리디렉션하므로 공개용 브라우저 키가 필요하지 않습니다.

범위를 명심하세요: 이 가이드는 웹 구독만 판매합니다. iOS/Android 앱 내 구매는 Apple과 Google 빌링을 거쳐야 하며—Stripe Checkout은 불가—모바일이 RevenueCat을 사용하는 이유입니다.

• 데이터베이스 설정
• 모바일 구매용 RevenueCat 설정

Stripe 계정 만들기

1. stripe.com → Start now를 열고 이메일로 가입합니다.

2. 온보딩은 비즈니스에 대해 묻습니다—테스트 모드에서는 모든 질문을 건너뛰어도 전체 샌드박스를 사용할 수 있습니다. 실제 결제를 받기 전에만 활성화를 완료하세요.

예상 결과: 헤더에 Test mode 토글이 보이는 대시보드에 도달합니다. 아래 모든 작업에서 켜둡니다—라이브 키는 나중에 프로덕션 시크릿 저장소에 넣을 것이지 노트북 env 파일에 넣는 것이 아닙니다.

API 키 복사

1. 대시보드에서 Developers → API keys를 엽니다.

2. 두 개의 테스트 키가 보입니다: Publishable key pk_test_…와 마스크된 Secret key. 시크릿 옆의 Reveal test key를 클릭하고 sk_test_… 값을 복사합니다.

킷은 시크릿 키만 필요합니다: 체크아웃 세션은 서버에서 생성되고 사용자는 Stripe의 호스팅 페이지로 리디렉션되므로 공개 키는 env 변수에 들어가지 않습니다. 나중에 만드는 제품이 Stripe.js를 추가하면 클라이언트 측에서 공개 키를 사용하겠지만 킷의 빌링 흐름은 사용하지 않습니다.

sk_test_… 키는 샌드박스 계정의 완전한 자격 증명입니다: apps/web/.env.local 또는 시크릿 저장소에 두고 NEXT_PUBLIC_/EXPO_PUBLIC_ 변수나 Git에 절대 넣지 마세요.

제품 및 가격 만들기

1. Product catalog → Add product를 엽니다.

2. 플랜 이름을 따서 이름을 지정하고—Pro는 킷에 포함된 플랜과 일치합니다—가격을 지정하고 Recurring(예: 월간)을 선택합니다: 킷의 체크아웃은 구독 모드 세션을 생성하므로 일회성이 아닌 반복 가격이 필요합니다.

3. 저장하고 제품을 열어 price id를 복사합니다—price_…로 시작합니다(제품 ID인 prod_…가 아닙니다).

제공된 pro 플랜은 이미 Monthly/Yearly 토글을 표시합니다: 월간은 STRIPE_PRICE_ID로 체크아웃하고 연간 옵션에는 STRIPE_PRICE_ID_PRO_YEARLY의 두 번째 반복 가격이 필요합니다—없으면 연간 체크아웃이 price-unconfigured로 실패합니다. 플랜 이름, 금액, 구매가 부여하는 것은 apps/web/src/product-plans.ts에서 변경합니다—Stripe는 돈 쪽을 저장하고 플랜 파일은 인타이틀먼트 쪽을 저장합니다.

webhook 엔드포인트 추가

webhook이 실제로 액세스를 부여하는 것입니다: 킷은 서명된 Stripe 이벤트가 도착한 후에만 인타이틀먼트를 뒤집으므로 체크아웃 리디렉션만으로는 아무것도 증명되지 않습니다.

1. Developers → Webhooks → Add endpoint를 엽니다.

2. Endpoint URL: 공개 URL에 /api/billing/webhook을 붙인 것—예: https://yourdomain.com/api/billing/webhook. 다른 빌링 공급자는 해당 디렉터리 아래 자체 경로를 갖고 Stripe의 수신기는 루트에 있습니다.

3. Select events에서 킷이 처리하는 이벤트를 선택합니다: checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, invoice.paid, invoice.payment_failed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted.

4. 엔드포인트를 만들고 페이지를 열어 Signing secret 아래의 Reveal을 클릭하고 whsec_… 값을 복사합니다—각 엔드포인트에는 자체 시크릿이 있습니다.

로컬 개발은 Stripe의 서버를 받을 수 없으므로 대신 Stripe CLI를 사용합니다: 한 번 stripe login한 후 다른 터미널에서 stripe listen --forward-to localhost:3000/api/billing/webhook을 실행합니다. 임시 whsec_…가 출력됩니다—stripe listen이 실행되는 동안 대시보드 값이 아니라 그 값이 .env.local에 들어갑니다.

앱에 값 추가

아래 줄을 apps/web/.env.local에 설정합니다. BILLING_PROVIDER=stripe가 어댑터를 선택하고 나머지 세 개는 키, 가격, 서명 시크릿입니다. 이 중 하나라도 누락된 상태로 공급자를 활성화하면 시작이 실패하고 변수를 지목합니다.

세 개의 STRIPE_* 값은 모두 서버 전용입니다—NEXT_PUBLIC_/EXPO_PUBLIC_에 넣지 말고 커밋도 하지 마세요. 프로덕션은 호스트의 시크릿 매니저를 통해 받습니다(배포 가이드가 Secret Manager를 다룹니다). 편집 후 개발 서버를 재시작하세요.

# apps/web/.env.local
BILLING_PROVIDER=stripe
STRIPE_SECRET_KEY=sk_test_…
STRIPE_PRICE_ID=price_…
STRIPE_WEBHOOK_SECRET=whsec_…   # `stripe listen` value locally; endpoint signing secret in production
# STRIPE_PRICE_ID_PRO_YEARLY=price_…   # required for the shipped Yearly toggle

확인 및 문제 해결

stripe listen --forward-to localhost:3000/api/billing/webhook을 시작하고 실행 상태로 두고 개발 서버를 재시작한 다음 /billing을 열어 Pro 플랜을 선택하고 테스트 카드 4242 4242 4242 4242, 미래 만료일, 임의 CVC로 Stripe의 호스팅 체크아웃을 완료합니다.

예상 결과: 앱이 /billing?checkout=success로 돌아오고 워크스페이스의 인타이틀먼트가 활성으로 뒤집힙니다—listen 터미널이 전달된 이벤트를 기록하고 대시보드의 Developers → Webhooks → 해당 엔드포인트에 녹색 전달이 표시됩니다.

체크아웃을 클릭하지 않고 수신기를 시험하려면 stripe trigger checkout.session.completed가 listen 포워더를 통해 합성 이벤트를 보냅니다.

일반적인 실패: 모든 전달에서 400은 서명 시크릿이 해당 엔드포인트와 일치하지 않음을 의미합니다—올바른 엔드포인트의 whsec_…를 다시 복사하고 env를 업데이트하세요. 조용한 무동작은 BILLING_PROVIDER가 아직 local임을 의미합니다. 테스트 설정에 섞인 sk_live_ 키는 잘못된 모드의 키를 복사한 것입니다—테스트와 라이브를 엄격히 분리하세요.

킷은 Lemon Squeezy, Creem, Polar, Whop, Paddle, Dodo, PayPal에도 동일한 단일 계약 어댑터를 제공합니다—같은 흐름에 콘솔과 env 이름만 다릅니다—모바일 구매는 Stripe가 아닌 RevenueCat에 남습니다.

• 빌링 공급자 비교
• 다음으로 Resend 이메일 추가
• 모바일 구매는 RevenueCat 사용