Stripe 구성 및 웹훅

설치 및 설정

어떤 단계를 시작하기 전에 시작하기 전에 및 터미널 기본 사항을 읽어보세요. 이 지침에서는 VS Code에서 전체 supastack 단일 저장소를 열었다고 가정합니다. 해당 루트 package.json은 저장소 루트를 표시합니다. pnpm 명령에서 작업 영역 패키지는 앱 또는 공유 코드 폴더입니다. 제품에서 작업공간은 팀의 데이터 컨테이너이자 보안 경계입니다. corepack pnpm --filter ... 명령이 해당 루트에서 실행되는 동안 monorepo에서 하나의 패키지를 선택합니다. 동기화된 모바일 또는 데스크톱 폴더만 열었다면 웹 백엔드, Docker 설정 또는 루트 스크립트가 포함되지 않습니다. 이 모노 저장소 또는 연결 가능한 호스팅 서버에서 백엔드를 실행하고 플랫폼 폴더의 자체 스크립트를 사용하세요. 환경 변수는 로컬 .env 파일이나 호스팅 대시보드에 저장된 명명된 설정입니다. 관련 앱을 변경한 후 다시 시작하고, NEXT_PUBLIC_ 및 EXPO_PUBLIC_ 값에서 서버 비밀을 유지하세요.

1. apps/web/.env.local를 열고 결제 화면을 학습하는 동안 BILLING_PROVIDER=local를 유지하세요.

2. 실제 통합을 위해 하나의 공급자에서 테스트 모드 제품을 만든 다음 해당 서버 키와 웹훅 비밀을 웹 호스트의 개인 환경 설정에 추가합니다. 웹훅은 결제, 갱신 또는 취소 후 청구 서비스가 앱에 보내는 서명된 메시지입니다. 엔드포인트 경로는 이 가이드의 코드 예제에 나열되어 있습니다.

3. corepack pnpm --filter @supastack/web dev로 웹을 시작하고 샌드박스만 테스트합니다. 예상: 확인된 웹훅은 로그인된 작업 영역의 자격을 업데이트합니다. 결제 페이지만 열면 액세스 권한이 부여되지 않습니다.

통합하는 동안 샌드박스/테스트 자격 증명을 사용하세요. BILLING_PROVIDER와 공급자의 서버 전용 비밀을 구성합니다: 스트라이프 → STRIPE_SECRET_KEY, STRIPE_PRICE_ID, STRIPE_WEBHOOK_SECRET; 레몬스퀴지 → LEMONSQUEEZY_API_KEY, LEMONSQUEEZY_STORE_ID, LEMONSQUEEZY_VARIANT_ID, LEMONSQUEEZY_WEBHOOK_SECRET; creem → CREEM_API_KEY, CREEM_PRODUCT_ID, CREEM_WEBHOOK_SECRET(샌드박스의 경우 CREEM_TEST_MODE=true); 극성 → POLAR_ACCESS_TOKEN, POLAR_PRODUCT_ID, POLAR_WEBHOOK_SECRET (POLAR_SERVER); 굉장한 → WHOP_API_KEY, WHOP_PLAN_ID, WHOP_WEBHOOK_SECRET; 패들 → PADDLE_API_KEY, PADDLE_PRICE_ID, PADDLE_WEBHOOK_SECRET (PADDLE_ENVIRONMENT); 도도 → DODO_PAYMENTS_API_KEY, DODO_PRODUCT_ID, DODO_PAYMENTS_WEBHOOK_KEY (DODO_PAYMENTS_ENVIRONMENT); 페이팔 → PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_PLAN_ID, PAYPAL_WEBHOOK_ID (PAYPAL_ENVIRONMENT). 가격/제품은 의도된 반복 구독을 나타내야 합니다.

Webhook endpoint: /api/billing/webhook (stripe), /api/billing/webhook/lemonsqueezy, /api/billing/webhook/creem, /api/billing/webhook/polar, /api/billing/webhook/whop, /api/billing/webhook/paddle, /api/billing/webhook/dodo, /api/billing/webhook/paypal
Checkout endpoint: /api/billing/checkout
Portal endpoint: /api/billing/portal

복사 명령

설명을 따라 명령이 실행되는 폴더를 확인하세요. 두 개의 터미널에 레이블이 지정되어 있으면 두 개의 터미널 창을 열고 두 번째 명령을 사용하는 동안 첫 번째 명령을 계속 실행하세요.

corepack pnpm --filter @supastack/web dev

구현 워크플로

웹훅 엔드포인트 구성은 docs/real-provider-smoke.md의 라이프사이클 이벤트 목록을 따르세요. 서명 검증에는 엔드포인트에 해당하는 웹훅 시크릿이 필요합니다. 체크아웃 리디렉션만으로는 절대 액세스를 부여해서는 안 됩니다.

서버 액션 경계의 권한이 유료 작업이 허용되는지 결정합니다. 반복된 이벤트를 안전하게 처리하고 고객/구독 레코드를 올바른 워크스페이스로 범위 지정하세요. 웹 체크아웃은 네이티브 구매와 분리되어 있습니다.

계획이 부여하는 핵심은 여러 표면에서 공유되는 제품 어휘입니다. src/product-plans.ts의 ProductPlan.entitlement는 계획이 지불되는 동안 원장에 기록된 소문자 기계 키를 선언합니다(키트는 pro 및 평생에 'ai.reference-task'를 제공하고 src/billing-runtime.ts는 이를 BFF에 전달합니다). 동일한 키는 CMS 항목의 require_entitlement 필드와 EntitlementGate 구성 요소의 entitlementKey 소품 동등 비교입니다. 'ai.reference-task'에 게이트된 항목은 해당 권한을 보유한 모든 작업 공간에 대해 잠금 해제되는 반면, 계획이 부여되지 않은 키는 모든 사람에 대해 잠긴 상태로 유지됩니다.

검증 및 문제 해결

웹훅이 거부된 경우 정확한 샌드박스 URL 및 공급자 대시보드의 서명 비밀을 서버 설정과 비교하고 해당 공급자가 요청을 localhost로 전달해야 하는지 확인하세요. 체크아웃이 작동하지만 액세스가 계속 잠겨 있는 경우 웹후크 결과와 계획의 자격 키를 검사하세요. 이 지역 가이드를 따르는 동안에는 실시간 결제 자격 증명으로 테스트하지 마세요.

샌드박스에서 활성화, 업데이트, 취소, 유효하지 않은 서명, 반복된 이벤트를 테스트하세요. 처리 후 지속된 액세스 상태를 검사하세요. 소비되지 않은 체크아웃 세션 생성은 연결성만 증명할 뿐 라이프사이클 풀필먼트가 아닙니다.