Stripe

如果你已在接入支付中选择 Stripe，继续按这篇配置。先使用 Stripe 测试模式完成一笔测试购买，准备上线时再换成正式凭据与正式回调端点。

获取 Stripe 密钥

从 Stripe Dashboard 获取密钥，并设置 STRIPE_SECRET_KEY。 Stripe

密钥安全

网关凭证只保存在服务端环境变量或部署平台密钥中。切勿暴露到前端或版本库。

获取 Stripe Webhook 密钥

创建webhook： Stripe 填写回调地址并选择事件类型： Stripe

在 Stripe Dashboard 添加 Webhook 端点，将 URL 设为：

https://example.com/api/muse-billing/notify/muse_stripe

选择配置需要监听的事件类型（或全部）：

checkout.session.completed
customer.subscription.*
invoice.*

把 Stripe webhook 签名密钥写入 STRIPE_WEBHOOK_SECRET。 Stripe

密钥安全

Webhook secret 保存在服务端环境变量中。与 Stripe 不一致会导致全部 webhook 被拒绝。

创建产品，复制对应的价格 ID

为你提供的套餐创建月付循环价格、年付循环价格和一次性价格。虽然变量名包含 PRODUCT_ID，这里应填写 Stripe Price ID（price_...），而不是 Product ID（prod_...）：

BILLING_DEFAULT_GATEWAY="muse_stripe"
STRIPE_PRODUCT_ID_PRO_MONTHLY="price_your_monthly_price"
STRIPE_PRODUCT_ID_PRO_YEARLY="price_your_yearly_price"
STRIPE_PRODUCT_ID_LIFETIME="price_your_one_time_price"

只配置你启用的套餐。应用展示的币种、金额和周期应与 Stripe 价格一致；价格与密钥应属于同一个测试或正式模式。公开定价页仍使用稳定的应用套餐 ID。

当前网关仅在映射值以 price_ 开头时使用 Stripe 已有价格。其他值会根据应用订单生成内联 price_data，并不会自动选中某个 Stripe Product。跟随本篇在 Dashboard 管理价格时，请使用明确的 Price ID。

Stripe Stripe

本地开发测试

下载 Ngrok

Ngrok下载（https://dashboard.ngrok.com/get-started/setup/windows）是反向代理工具，用于将本地开发服务器暴露到公网。

Ngrok

运行

ngrok http 3000

Ngrok

回调域名

将上述终端域名填向上述webhook中的回调地址

测试

测试卡号	预期结果
`4242 4242 4242 4242`	支付成功 (Successful payment)
`4000 0000 0000 0002`	卡被拒绝 (Card declined)
`4000 0000 0000 9995`	余额不足 (Insufficient funds)
`4000 0000 0000 0127`	CVC 错误 (Incorrect CVC)
`4000 0000 0000 0069`	卡已过期 (Expired card)

利用上述测试信用卡，可以在本地模拟生产环境进行各种支付测试，包括订阅、一次性购买、用户支付管理等。

开启支付宝/微信支付

如果你的产品需要支持支付宝/微信支付，可以在Stripe后台开启。

Stripe

工作原理解析

了解 Muse Billing 是如何将 Stripe 融入系统中的。

集成文件分布

packages/billing/src/gateways/stripe/gateway.ts

src/modules/muse-billing/lib/services/launch.ts

src/backend/api/routes/muse-billing/router.ts

文件	职责
`stripe/gateway.ts`	Stripe 网关实现：Checkout Session、Webhook 解析、合约同步。
`services/launch.ts`	结账编排；客户门户与 Webhook 分别在同目录 customer-hub.ts / webhook.ts。
`router.ts`	API 路由：暴露 `/api/muse-billing/*` 接口。

核心工作流

针对付款和获取 Customer Hub 的动作流程如下：

前端调用 POST /api/muse-billing/launch，传入 productId、gatewayId（可选，默认由 orchestrator 选择）等参数。

服务端从 STRIPE_PRODUCT_ID_* 读取映射值；price_ 开头的值使用已有 Stripe Price，否则根据订单生成内联价格数据。

创建 Stripe Checkout Session，返回 launchUrl 供前端跳转至结账页。

用户完成支付后，Stripe 发送 Webhook，服务端校验签名并同步合约状态到数据库。

当用户需要进入平台后，通过调用 POST /api/muse-billing/customer-hub 取得跳转 Stripe 官方 Customer Portal 的链接来管理订阅或下载收据等。