计费配置

先接通一个网关即可。目标是完成一次完整沙盒购买：用户登录、结账、Webhook 到达，应用显示正确套餐。

开始前准备

准备可运行的应用、具备沙盒/测试权限的支付账号，以及要售卖的套餐、金额、币种和周期。Webhook 需要可公开访问的 HTTPS 测试部署，或服务商支持的转发工具。

首次测试不要使用正式密钥或真实扣款。配置准备好之前，可以保持 config.payments.enableBilling=false。

1. 选择一个支付网关

网关	配置教程	主要凭据
Creem	Creem	`CREEM_API_KEY`
Stripe	Stripe	`STRIPE_SECRET_KEY`
Dodo Payments	Dodo	`DODO_PAYMENTS_API_KEY`
Waffo	Waffo	`WAFFO_MERCHANT_ID` 与 `WAFFO_PRIVATE_KEY`

根据商户资质、目标市场、支付方式与业务需求选择。具体可用能力以服务商和账号为准，不需要同时开通四个账号。

2. 关联你的套餐

在 packages/config/src/index.ts 的 payments.productCatalog 保留稳定的应用套餐 ID。所选应用内：

src/config/saas/pricing-desc.ts：套餐名称、描述和权益文案。
src/config/saas/pricing-desc-usage.ts：金额、币种、订阅周期和可购买项。

在网关后台创建对应产品/价格，按网关教程复制正确类型的 ID。将你启用的套餐映射到该网关环境变量。例如 Stripe 在应用 .env.local 中使用：

BILLING_DEFAULT_GATEWAY="muse_stripe"
STRIPE_SECRET_KEY="YOUR_TEST_SECRET_KEY"
STRIPE_WEBHOOK_SECRET="YOUR_TEST_WEBHOOK_SECRET"
STRIPE_PRODUCT_ID_PRO_MONTHLY="YOUR_MONTHLY_PRICE_ID"
STRIPE_PRODUCT_ID_PRO_YEARLY="YOUR_YEARLY_PRICE_ID"
STRIPE_PRODUCT_ID_LIFETIME="YOUR_ONE_TIME_PRICE_ID"

网关价格、币种、周期要与应用配置一致。originalAmount 只展示划线对比价，不修改网关价格。本地与生产凭据的配置方式见环境变量。

3. 注册 Webhook

使用你的测试 origin 加对应路径：

网关	路径
Creem	`/api/muse-billing/notify/muse_creem`
Stripe	`/api/muse-billing/notify/muse_stripe`
Dodo	`/api/muse-billing/notify/muse_dodo`
Waffo	`/api/muse-billing/notify/muse_waffo`

按网关教程配置签名密钥与事件列表。Waffo 使用 SDK 验签与 WAFFO_ENVIRONMENT=test，没有独立 Webhook secret 变量。浏览器返回成功页不代表已获得付费权限，服务端会根据 Webhook 更新状态。

4. 完成第一次沙盒购买

开启 payments.enableBilling，使用测试配置重启/重新部署，登录开发用户。打开 /pricing，选择已配置套餐，用服务商沙盒方式完成支付。等待 Webhook 后，检查用户套餐和账号计费页面。

确认结果

定价页展示正确套餐，托管结账金额、币种和周期符合预期。
网关后台显示 Webhook 投递成功。
刷新后，购买用户的套餐与有效期正确。
订阅套餐可以通过对应客户门户管理。
失败或取消的结账不会获得付费权限。

常见问题

问题	处理方式
网关不可选或结账失败	检查对应凭据和产品映射，本地修改后重启
找不到产品/价格	对照网关教程检查 ID 类型与测试/正式环境
Webhook 没有到达	使用公开 HTTPS 地址或转发工具，查看网关投递日志和 URL
签名被拒绝	匹配该端点签名密钥；Waffo 检查签名请求头和环境
结账成功但套餐没更新	排查 Webhook 投递、服务端报错和合约匹配，而非只看返回页

切换正式环境前，创建正式产品、替换测试凭据和 Webhook 配置，并完成上线检查清单。生产不要使用开发 seed 账号。