For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh-tw/docs/modules/billing-configuration.md (or send Accept: text/markdown).
Stripe 配置與 webhook
把 Web 訂閱連到服務端持有的許可權。
安裝與配置
在執行任何步驟之前，請閱讀開始之前 和終端基礎知識。這些說明假設您在 VS Code 中開啟了完整的 supastack monorepo；它的根 package.json 標記儲存庫根。在 pnpm 命令中，工作區包是應用程式或共享程式碼資料夾；在產品中，工作空間是團隊的資料容器和安全邊界。 corepack pnpm --filter ... 從 monorepo 選擇一個包，同時從其根執行命令。如果您僅開啟同步的移動或桌面資料夾，則它不包含 Web 後端、Docker 設定或根指令碼：從此 monorepo 或可訪問的託管伺服器執行後端，並使用平臺資料夾自己的指令碼。環境變數是儲存在本地 .env 檔案或託管儀錶板中的命名設定；更改後重新啟動相關應用程式，並將伺服器機密保留在 NEXT_PUBLIC_ 和 EXPO_PUBLIC_ 值之外。
1.開啟apps/web/.env.local並在學習結帳螢幕時保留BILLING_PROVIDER=local。
2. 要實現真正的整合，請在一個提供商中建立測試模式產品，然後將其伺服器金鑰和 Webhook 機密新增到 Web 主機的私有環境設定中。 Webhook 是計費服務在結帳、續訂或取消後傳送到您的應用程式的簽名訊息；本指南的程式碼示例中列出了端點路徑。
3. 使用 corepack pnpm --filter @supastack/web dev 啟動 Web 並僅測試沙箱。預期：經過驗證的 Webhook 會更新已登入工作區的權利；單獨開啟結賬頁面並不授予訪問許可權。
整合時使用沙箱/測試憑據。配置 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 中的生命週期事件清單配置 webhook 端點。簽名校驗需要與該端點匹配的 webhook 金鑰。僅有結賬跳轉絕不能授予訪問。
服務端動作邊界的許可權決定是否允許付費工作。安全地處理重複事件，並把客戶/訂閱記錄劃定到正確的工作區。Web 結賬與原生購買保持分離。
計劃授予的關鍵是跨表面共享的產品詞彙：src/product-plans.ts 中的 ProductPlan.entitlement 宣告在支付計劃時寫入分類賬的小寫機器金鑰（該套件在專業版和生命週期中提供“ai.reference-task”；src/billing-runtime.ts 將其傳遞給 BFF）。相同的金鑰是 CMS 條目的 required_entitlement 欄位和 EntitlementGate 元件的 entitlementKey 道具平等比較的內容 - 在“ai.reference-task”上門控的條目可為持有該授權的任何工作區解鎖，而沒有計劃授予的金鑰對每個人都保持鎖定。
驗證與排障
如果 Webhook 被拒絕，請將提供商儀錶板中的確切沙箱 URL 和簽名金鑰與伺服器設定進行比較，並檢查該提供商是否需要將請求轉發到 localhost。如果結帳有效但訪問保持鎖定狀態，請檢查 Webhook 結果和計劃上的授權金鑰。在遵循本本地指南時，切勿使用即時支付憑證進行測試。
在沙箱中測試啟用、更新、取消、無效簽名與重複事件。處理後檢查已持久化的訪問狀態。只建立一個未消費的結賬會話，證明的只是連通性，不是生命週期履約。