Stripe 集成：订阅、一次性付款与积分
ShipAny 如何接好 Stripe Checkout、Webhook、订阅、优惠码和积分发放——全部在管理后台配置，无需在 Stripe 预先创建产品。
最后更新: 2026年10月8日
每个 ShipAny 模板都自带完整的 Stripe 集成：一次性购买和订阅的 Checkout、带签名校验的 Webhook、订阅生命周期处理、优惠码和自动发放积分——全部在管理后台配置，而不是写在环境变量里。
包含哪些能力
- 一次性付款和订阅：根据订单类型自动选择 Checkout 模式（
payment或subscription）。 - 无需在 Stripe 预建产品：订单行项目以内联的
price_data发送，价格以你自己的价格配置为准。 - 银行卡、微信支付、支付宝：一次性付款可用的支付方式来自后台设置（
card、wechat_pay、alipay）。Stripe 只在一次性付款中支持微信支付和支付宝，订阅仍使用 Stripe 默认方式。 - 优惠码：用户可以在结账页输入 Stripe 优惠码，也可以预先为会话应用优惠码。
- 复用客户：创建新客户前先按邮箱查找已有的 Stripe 客户。
- 自助取消订阅：用户可以在账户设置中取消订阅；如需使用 Stripe 账单门户，Provider 也已提供对应能力。
支付流程
- 用户点击套餐，
POST /api/payment/checkout创建订单（状态created）和 Stripe Checkout 会话。 - 付款后 Stripe 跳回成功页，并向
/api/payment/notify/stripe发送 Webhook。 - 使用原始请求体和你的签名密钥校验 Webhook 签名。
- 订单被标记为
paid，ShipAny 在同一个数据库事务里创建或更新订阅，并发放套餐积分。
事务内会用 SELECT … FOR UPDATE 锁住订单行，因此 Webhook 重试和同步回调不会对同一笔付款重复发放积分。
处理的 Webhook 事件
| Stripe 事件 | ShipAny 的处理 |
|---|---|
checkout.session.completed | 标记订单已支付、创建订阅、发放积分 |
invoice.payment_succeeded | 续费：延长订阅周期并发放下一周期积分 |
invoice.payment_failed | 确认收到，不改变状态——由 Stripe 自己的重试机制催缴 |
customer.subscription.updated | 同步套餐、状态和周期变化 |
customer.subscription.deleted | 将订阅标记为已取消 |
配置步骤
- 在 Stripe 后台复制 Secret Key 和 Publishable Key。
- 添加 Webhook 端点
https://<你的域名>/api/payment/notify/stripe，订阅上面 5 个事件，复制它的 Signing Secret。 - 在 ShipAny 中打开 管理后台 → 设置 → 支付 → Stripe，填入 Secret Key、Publishable Key 和 Webhook Signing Secret，打开 Enable Stripe。配置保存在数据库中（设置了
CONFIG_ENCRYPTION_KEY时会加密存储）。 - 在价格配置中定义套餐和积分数量，然后用 Stripe 测试模式下单验证。
避坑
- Webhook 要指向实际运行应用的域名。 如果迁移了托管平台（比如迁到 Cloudflare Workers），只要域名不变 Webhook 地址也不变——但迁移后务必实测一笔真实付款。
- 确认生产环境真的读到了支付配置。 首页正常不代表 Stripe 密钥被读取了。
/api/config/public应返回stripe_enabled: "true"，否则说明应用没有读到配置表。 - 订阅里用不了微信支付 / 支付宝。 Stripe 只在一次性付款中提供它们；需要国内周期扣款时请使用原生支付宝或微信支付渠道。
其他支付渠道
Stripe 是默认渠道，同一条「订单 → 订阅 → 积分」流程也适用于 Creem、支付宝和微信支付。可以在管理后台选择默认渠道，或让用户在结账时自行选择。