Starter 应用

Stripe 计费

配置订阅价格、幂等结账、Webhook、积分、客户门户安全与对账。

已与启动模板提交 7d452a6 同步。

为 Plus 与 Max 创建稳定的月付/年付 Stripe Price,设置 STRIPE_PRICE_*STRIPE_PRIVATE_KEYSTRIPE_WEBHOOK_SECRET。CNY Price 可选。金额与产品目录在 src/config/billing.ts,Price ID 只留在服务端。

结账仅限组织 owner,并要求 Idempotency-Key。服务会先创建购买意图/订单,因此同一请求重试只产生一次效果;主动再次购买必须使用新 key。多个订阅可共存,entitlement resolver 会合并它们。

Webhook 契约

公开 /api/pay/notify/stripe,至少订阅 checkout 完成/过期、subscription 新增/更新/删除、invoice paid/payment failed 与 refund/dispute。处理器验证签名、按 Stripe event ID 去重、用事件时间处理乱序,并确保积分权益只发一次;续费 invoice 会创建新订单与月度积分。

退款与争议会被评估并提示人工处理,模板不会静默扣回已消费积分。使用内置 Stripe 对账命令和管理端事件视图修复不确定状态。

Portal 与本地测试

创建 Stripe Billing Portal 配置并在生产设置其 ID。Portal 内必须禁用订阅变更;不安全时模板会 fail closed。

stripe listen --forward-to localhost:3000/api/pay/notify/stripe

上线前测试重复结账、延迟/重复 webhook、续费、失败、取消、退款与 Portal。生产只用 live key,并只接收 live-mode 事件。

Stripe 计费 · Sushi SaaS