Stripe 计费

Setup

1. 配置 Stripe 凭据

配置 Secret Key、Webhook Secret 以及不同环境的回调地址。

2. 创建产品与价格（月付/年付）

建议每个套餐对应一个 Stripe Product，在同一 Product 下创建两条 recurring price：

• 月付：recurring.interval = month
• 年付：recurring.interval = year

并为每个价格设置全局唯一的 lookup_key。

积分包（一次性价格）建议使用：

• credits_starter
• credits_growth
• credits_scale

注意：同一个 Stripe 账户内所有 lookup_key 都必须唯一。

3. 年付优惠配置

推荐：直接创建“已折扣”的年付价格（如月价 * 12 * 0.9）。

可选：通过 Coupon/Promotion Code 实现优惠，但要确保回调幂等和权益发放一致。

4. 配置环境变量价格引用

本项目支持两种价格引用方式：

• 直接 price_id（price_xxx）
• lookup 引用（lookup:creator_monthly 或 creator_monthly）

可通过环境变量覆盖 lookup 回退：

• STRIPE_PRICE_SUB_CREATOR_MONTHLY
• STRIPE_PRICE_SUB_CREATOR_YEARLY
• STRIPE_PRICE_SUB_PRO_MONTHLY
• STRIPE_PRICE_SUB_PRO_YEARLY
• STRIPE_PRICE_SUB_SCALE_MONTHLY
• STRIPE_PRICE_SUB_SCALE_YEARLY
• STRIPE_PRICE_CREDITS_STARTER（兼容 STRIPE_PRICE_CREDITS_500）
• STRIPE_PRICE_CREDITS_GROWTH（兼容 STRIPE_PRICE_CREDITS_1200）
• STRIPE_PRICE_CREDITS_SCALE（兼容 STRIPE_PRICE_CREDITS_3000）

5. 验证关键回调事件

重点验证支付成功、订阅续费、扣费失败、取消订阅等关键事件。

6. 执行 seed 写入产品与支付配置

bun run seed:prod -- --env-file ../../apps/ship-api/.env.production

Bunship 已经实现的部分

• 订阅 Checkout 与一次性支付 Checkout
• Stripe Customer Portal（用户自助管理订阅）
• 回调入口与事件处理：apps/ship-api/src/services/webhook/stripe.ts
• 续费事件幂等发放积分（invoice.paid / invoice.payment_succeeded）

代码位置

• 订阅与订单 API：apps/ship-api/src/module/subscription.ts、apps/ship-api/src/module/orders.ts
• Webhook 路由：apps/ship-api/src/module/webhook/stripe.ts
• Webhook 业务逻辑：apps/ship-api/src/services/webhook/stripe.ts
• 产品与价格 seed：packages/db/src/drizzle/seed/product.ts

买家上线检查

1. Stripe 后台产品/价格与 seed 映射一致。
2. 生产环境 webhook 可被 Stripe 正常访问。
3. 续费、失败扣费、取消订阅都做过回归。
4. 用户端与后台端订单/订阅状态展示一致。

Next Steps