支付生命周期

一次结账如何变成已支付订单:服务端定价、通过 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 和回调都会运行结算,所以每一步都可以安全地重复:

  1. 订单状态变为 paid。
  2. 写入发票 invoice_<orderId>。
  3. 订阅订单写入 subscription_<orderId>,并带上服务商订阅 id。如果回调先完成结算,之后到达的 Webhook 会补上该 id。
  4. 以上写入提交之后,再把已付订单通知给每个已启用的履约插件。

履约发生在提交之后

计费只负责订单、付款和退款。一笔已付订单让买家得到什么,由销售它的插件定义:该插件向 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、回调和未配置的尝试都会连同签名结果、状态和原始载荷一起保存,管理员可以逐条查看。订单、发票、订阅、退款和履约是各自独立的记录。

相关文件

src/server/db/repositories/billing-payment.repository.ts
src/server/functions/billing-payment.ts
src/server/payments/wechatpay.ts
src/server/payments/alipay.ts
src/server/payments/waffo.ts
src/server/billing/fulfilment.ts
src/server/billing/fulfilment-types.ts
src/server/billing/plan-credits-fulfiller.ts
src/server/db/repositories/billing-fulfilment.repository.ts
src/components/billing/app-billing-pages.tsx
src/components/billing/billing-workspace.tsx
src/components/billing/wechat-pay-checkout.tsx

下一步