管理订单、退款和订阅

完成后,你可以为订单退款、取消或恢复订阅、让买家自助管理账单,并重新处理失败的 webhook。

成交之后,运营人员在后台的 商业化 和 安全 区域操作,买家使用自己的账单页面。所有变更都通过支付服务商执行,所以可用的操作取决于当前启用的服务商。

准备工作

  • 一个已接入并至少完成过一笔付款的服务商,见 接入支付服务商。
  • 与操作对应的权限:退款需要 orders.write,订阅变更需要 subscriptions.write,重试 webhook 需要 webhooks.write。打开页面需要对应的 .read 权限。
  • 在后台退款需要 Stripe、微信支付或支付宝;Creem 和 Waffo 的退款在各自后台操作。订阅变更和客户门户需要 Stripe 或 Creem。

为订单退款

打开订单

进入 商业化 → 订单(/admin/orders),打开订单。

创建退款

填写要退回的 金额 cents 和 原因,点击 创建退款。退款记录的状态为待处理、成功、失败或未配置。

全额退款成功后,该订单签发的授权被撤销。部分退款不撤销任何授权。退款不会改变订单状态,也不会收回积分,需要时请手动扣减积分,见 用积分对用量计费。Creem 退款需要在 Creem 后台操作。

取消或恢复订阅

打开订阅

进入 商业化 → 订阅(/admin/subscriptions),打开订阅。

执行变更

点击 周期结束时取消 停止续费,或点击 恢复订阅 撤销取消。变更会发送给服务商。

两个操作都需要服务商的订阅 id,这个 id 包含在付款成功的 webhook 中。

让买家管理账单

买家在 /app/billing 查看当前方案、订单和发票,并可导出 CSV。更换卡片或取消订阅则在服务商的客户门户中进行。

打开门户页面

买家打开 /app/billing/portal。

创建会话

Provider 保持 已配置默认值,填写 Provider customer ID(Stripe 为 cus_…),点击 创建 portal session。服务商创建会话后,页面显示 Portal 已就绪: 和门户地址。否则显示状态。

替换门户表单

门户页面是一个简单表单。在你的产品中,把它换成一个传入已保存客户 id 的按钮。

重试失败的 webhook

签名正确但处理失败的 webhook(例如遇到临时的数据库错误)可以重新处理。

找到事件

进入 安全 → Webhooks(/admin/billing-webhooks),打开事件查看 payload、签名结果和错误信息。

重试

在失败的事件上点击 重试。系统重新处理已保存的 payload,并把结果记录为一条新事件。

签名无效的事件无法重试,请在服务商后台重新发送。

验证

  • 退款后,订单页面列出该退款及其状态。全额退款后,买家的 /app/licences 中不再有该授权。
  • 点击 周期结束时取消 后,订阅页面的 周期结束时取消 显示为 是。恢复订阅 会把它改回 否。
  • 重试后,Webhooks 中出现同一 payload 的新事件。

pnpm validate:billing 会检查退款、订阅和 webhook 路径。设置好沙盒 id 后,pnpm validate:external 会真实调用客户门户、取消、恢复和退款接口。

常见问题

Stripe 退款提示没有可退款的 PaymentIntent

报错 The Stripe checkout session has no PaymentIntent to refund. 说明该结账 session 从未产生付款,没有可退回的款项。

取消或恢复返回 missing_provider_subscription

携带服务商订阅 id 的付款成功 webhook 还没有到达。到 Webhooks 查看该事件。如果没有,先注册 webhook。

退款记录为未配置或失败

未配置表示接单服务商的凭据在 支付配置 中缺失。退款失败时,Webhooks 中会有一条带错误信息的 refund.failed 事件。Stripe 以外的服务商会报 This payment provider does not support refunds through this adapter.,请在其后台退款。

门户页面提示门户未配置

当前服务商没有客户门户,只有 Stripe 和 Creem 提供。

参考

下一步