支付方案

支付配置决定了下单、续费、退款与积分发放的稳定性。下面只给可执行步骤，保证最快跑通生产链路。

支付方案选择

• Stripe：直连 PSP，适合已有主体/税务团队、需要完全掌控资金流的场景。
• Creem（MoR）：Merchant of Record 代收款与税务/合规，适合快速全球化收款。

Bunship 最少需要的变量

Stripe：

• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET

Creem：

• CREEM_API_KEY
• CREEM_WEBHOOK_SECRET

可选：

• PAYMENT_PROVIDER_DEFAULT（默认 stripe，只用 Creem 时建议设为 creem）

当前支持的支付产品类型

• 一次性支付：一次购买即可完成付款与发货/权益开通。
• 订阅支付：按月/年周期扣费，适合持续服务与积分定期发放。

订阅试用期说明

在订阅产品中可以配置 trialDays，表示试用天数：

• trialDays > 0：创建订阅时会附带试用期，试用结束后进入正常扣费周期。
• trialDays = 0：无试用期，订阅创建后直接进入正常扣费周期。

试用期只对订阅支付生效，不影响一次性支付。

通用启用步骤

1. 设置支付提供商相关环境变量。
2. 在 Admin → Products → 支付配置 中为每个产品添加配置：
   • provider：stripe 或 creem
   • externalPriceId：对应支付平台的价格/产品 ID
   • isActive：true
   • sortOrder：越小优先级越高
3. 重启 web + api。
4. 配置对应的 webhook 回调。

快速接入：Stripe

1. 创建产品与价格

建议一个套餐对应一个 Stripe Product，并创建两条 recurring price：

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

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

2. 绑定价格引用

externalPriceId 支持：

• 直接 price_xxx，或
• creator_monthly / lookup:creator_monthly（lookup key）

3. 配置 Webhook

回调地址：

https://你的域名/api/v1/webhook/stripe

建议事件：

• checkout.session.completed
• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted
• invoice.paid
• invoice.payment_failed
• payment_intent.succeeded
• payment_intent.payment_failed
• payment_intent.canceled

快速接入：Creem

1. 创建 Creem 产品

每个套餐/积分包都需要对应一个 Creem product_id。

2. 绑定产品 ID

将 externalPriceId 设置为 Creem 的 product_id。

3. 配置 Webhook

回调地址：

https://你的域名/api/v1/webhook/creem

Creem 的签名在 creem-signature header 中（HMAC-SHA256）。

建议事件：

• checkout.completed
• subscription.active
• subscription.paid
• subscription.canceled
• subscription.scheduled_cancel
• refund.created

买家上线检查

1. 产品的支付配置与平台产品/价格一致。
2. 生产环境 webhook 可被平台访问。
3. 续费、失败扣费、取消、退款流程全部验证。
4. 用户端与后台端订单/订阅状态一致。

Next Steps