支付生命周期
一次结账如何变成已支付订单:服务端定价、通过 Webhook 或回调由服务商确认、幂等结算以及退款。
Kernlift 中的一笔支付经历四个阶段:服务端按方案价格创建订单,买家在服务商的托管结账页付款,服务商确认付款,结算把订单变成发票,并通知履约插件交付方案所售的内容。接入服务商见接入支付服务商。
生命周期概览
| 阶段 | 触发方 | 结果 |
|---|---|---|
| 结账 | 已登录买家调用 POST /api/billing/checkout | 一个 pending 订单和托管结账 URL |
| 付款 | 买家在服务商页面操作 | 本地暂无变化 |
| 确认 | 签名 Webhook,或向服务商查询的返回回调 | 订单变为 paid、failed 或 canceled |
| 结算 | paid 确认 | 发票与订阅,先行提交 |
| 履约 | 结算,在订单提交之后 | 每个已启用的 billing.fulfilment 插件收到一次通知;内置的那个发放方案积分 |
| 退款 | 管理员 | 退款记录;退款成功后通知履约插件 |
同一时间只有一个默认服务商,所有方案都由它收款。唯一的例外是人民币钱包:以人民币(CNY)计价的方案在微信支付或支付宝启用且凭据齐全时由它们收款,优先微信支付,微信支付未就绪时走支付宝;其它币种仍走默认服务商。请求也可以显式指定服务商。各服务商共用这条生命周期,区别在于结账之后支持哪些操作。
| 服务商 | 订阅 | 客户门户 | 在管理后台退款 |
|---|---|---|---|
| Stripe | 支持,按方案周期每月或每年续费 | 支持 | 支持 |
| Creem | 取消与恢复 | 支持 | 不支持,只能在 Creem 控制台操作 |
| PayPal | 不支持,仅一次性付款 | 不支持 | 不支持 |
| DodoPayments | 无生命周期操作 | 不支持 | 不支持 |
| 微信支付 | 不支持,仅人民币一次性付款 | 不支持 | 支持 |
| 支付宝 | 不支持,仅人民币一次性付款 | 不支持 | 支持 |
| Waffo | 支持,使用在 Waffo 创建的月付、年付订阅商品各一个 | 不支持 | 不支持,只能在 Waffo 后台操作 |
打开 结账时允许使用优惠码 后,Stripe 和 Waffo 的结账页还会显示优惠码输入框,账单记录买家的实付金额。见提供优惠码。
结账价格由服务端决定
请求只指明方案 key。服务端加载该方案,把客户端发来的金额、币种和结账模式与之比较。发现任何不一致时,服务端会在调用服务商之前拒绝请求。
| 拒绝原因(HTTP 409) | 触发条件 |
|---|---|
unknown_plan | 不存在该 key 的方案 |
plan_inactive | 方案未启用 |
amount_mismatch | 金额、币种或结账模式与方案不一致 |
product_mismatch | 请求中的产品与方案所售产品不同 |
plan_interval_mismatch | 方案按订阅计费,但周期不是每月或每年;或者相反 |
provider_unsupported | 方案将由微信支付或支付宝收款,但它是订阅或不以人民币计价 |
| 履约方自定义的代码 | 某个已启用的履约插件在 canCheckout 中拒绝了这次购买 |
检查通过后,按方案价格保存一个 pending 订单。如果当前服务商未配置,订单标记为 failed,记录一条未配置事件,请求返回 409。否则服务商创建托管结账,其成功与取消 URL 都指回 /api/billing/callback/:provider。
微信支付没有托管收银页。Native 下单返回一个 weixin:// 开头的 code URL,它保存在订单上,买家跳转到站内的 /app/billing/pay/<orderId>。这个页面只为待支付订单的登录所有者显示二维码,每三秒向服务端查询一次订单状态,支付成功后跳到成功 URL。二维码两小时后失效。
支付宝直接把买家带到电脑网站收银台,地址经 RSA2 签名,两小时后失效。Waffo 在与套餐匹配的 Waffo 商品上创建托管结账会话:一次性商品,或月付、年付订阅商品,价格取自套餐(含税)。
只有服务商能把订单标记为已支付
买家返回时访问的 URL 不能证明已付款,因为任何人都能打开它。支付状态只会通过以下两种服务端确认之一发生变化。
签名 Webhook。 /api/billing/webhook/:provider 在读取任何内容之前,先在原始请求体上校验服务商签名。它从事件中找到本地订单 id,再把事件类型映射为已支付、失败或取消。每个事件 id 都会保存,所以重复投递只会返回已保存的结果,不再产生效果。签名无效的事件保存为失败,不改变任何状态。各服务商的 Webhook 注册见接入支付服务商。
返回回调。 /api/billing/callback/:provider 除了记录日志外忽略 status 查询参数。它向服务商查询已保存的结账,只有服务商报告已支付时才结算。否则把订单留给 Webhook 处理。随后买家被重定向到成功或取消 URL。
两者谁先到达谁就完成结算,后到的不再产生变更。失败的 Webhook 可以在管理后台重试,重试会以新的事件 id 重新应用签名有效的载荷。
微信支付遵循同样的规则,有两点不同。通知先用微信支付公钥验签,再用 APIv3 密钥解密。通知和服务端查单都只有在金额(分)等于订单金额且币种为 CNY 时才结算。
支付宝的异步通知把签名放在表单请求体里,用支付宝公钥验签;只有应用 APPID、卖家用户号(已填写时)和金额都与订单一致才结算。服务端 alipay.trade.query 查单只有在原始应答的签名通过、金额一致时才结算。Waffo 的 webhook 用保存的 webhook 公钥验签,服务端确认查询该订单的支付记录。两者都记录实际扣款金额,用了优惠码时账单上能看到折后金额。
结算是幂等的
Webhook 和回调都会运行结算,所以每一步都可以安全地重复:
- 订单状态变为
paid。 - 写入发票
invoice_<orderId>。 - 订阅订单写入
subscription_<orderId>,并带上服务商订阅 id。如果回调先完成结算,之后到达的 Webhook 会补上该 id。 - 以上写入提交之后,再把已付订单通知给每个已启用的履约插件。
履约发生在提交之后
计费只负责订单、付款和退款。一笔已付订单让买家得到什么,由销售它的插件定义:该插件向 billing.fulfilment 服务端插槽贡献一个履约方(fulfiller)。计费代码不按名称引用任何履约方。
| 钩子 | 调用时机 | 用途 |
|---|---|---|
canCheckout | 创建订单和支付会话之前 | 用一个代码和原因拒绝购买 |
onOrderPaid | 订单提交为已付之后,每个订单一次 | 交付方案所售的内容 |
onOrderRefunded | 退款在服务商侧成功之后,每笔退款一次 | 收回退款对应的内容 |
每次调用都记录在 billing_fulfilments 中,每个订单、履约方和事件一行。插入这一行就是认领,所以即使 Webhook 和回调同时结算同一个订单,每个履约方也只运行一次。履约方抛出异常不会撤销付款。这一行标记为 failed,写入一条审计记录,定时任务会在 1 分钟、5 分钟、30 分钟、2 小时和 12 小时后依次重试。第六次尝试仍失败则放弃,留给运营者处理。如果订单在此期间已退款或取消,paid 事件会被放弃,不再交付。被停用插件的履约方不会被调用。
模板自带一个履约方 plan-credits,由底座插件贡献。它把方案附带的积分发放一次,作为来源为 billing.order.<orderId> 的购买记录。见积分账本和编写履约插件。
退款与订阅变更
退款在管理后台创建,状态记录为 pending、succeeded、failed 或 not_configured。Stripe 针对 PaymentIntent 或 Charge 退款,遇到 Checkout Session 会先解析出对应的 PaymentIntent。微信支付通过退款接口退款:同步返回 SUCCESS 立即记为成功,PROCESSING 保持 pending,直到收到验签通过的 REFUND.SUCCESS 通知。支付宝通过 alipay.trade.refund 退款,以本地退款 id 作为 out_request_no,同一请求重复发送也只退一次。其他适配器报告不支持退款;Waffo 的退款和订阅变更在 Waffo 后台操作。是否全额退款按买家实付金额判断。退款成功后,履约插件会收到 onOrderRefunded,其中带有金额以及是否为全额退款。退款要收回什么由各插件决定。
取消订阅会把它设为在当前周期结束时终止,恢复则清除该标记。两者都需要结算时保存的服务商订阅 id。
记录了什么
每一次结账、Webhook、回调和未配置的尝试都会连同签名结果、状态和原始载荷一起保存,管理员可以逐条查看。订单、发票、订阅、退款和履约是各自独立的记录。