管理订单、退款和订阅
完成后,你可以为订单退款、取消或恢复订阅、让买家自助管理账单,并重新处理失败的 webhook。
成交之后,运营人员在后台的 商业化 和 安全 区域操作,买家使用自己的账单页面。所有变更都通过支付服务商执行,所以可用的操作取决于当前启用的服务商。
准备工作
- 一个已接入并至少完成过一笔付款的服务商,见 接入支付服务商。
- 与操作对应的权限:退款需要
orders.write,订阅变更需要subscriptions.write,重试 webhook 需要webhooks.write。打开页面需要对应的.read权限。 - 在后台退款需要 Stripe、微信支付或支付宝;Creem 和 Waffo 的退款在各自后台操作。订阅变更和客户门户需要 Stripe 或 Creem。
为订单退款
全额退款成功后,该订单签发的授权被撤销。部分退款不撤销任何授权。退款不会改变订单状态,也不会收回积分,需要时请手动扣减积分,见 用积分对用量计费。Creem 退款需要在 Creem 后台操作。
取消或恢复订阅
两个操作都需要服务商的订阅 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 提供。