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/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 结果和计划上的授权密钥。在遵循本本地指南时，切勿使用实时支付凭证进行测试。
在沙箱中测试激活、更新、取消、无效签名与重复事件。处理后检查已持久化的访问状态。只创建一个未消费的结账会话，证明的只是连通性，不是生命周期履约。