退款

退款为所有主题共用的 APay 核心能力。refunds.order_id 唯一,每笔订单固定一个退款 ID。实付金额、币种、原支付方式和交易号从已付款订单锁定,调用方不能指定金额、收款人或渠道结果。仅正金额已付款订单可申请;当前不支持部分退款或自动审核。

用户接口

两个接口均须登录且为订单本人;访问他人订单返回 404。只读订单 Token 不可提交申请。

  • GET /api/users/orders/:id/refund:返回 { data: Refund | null }。
  • POST /api/users/orders/:id/refund:请求 { "reason": "申请退款的原因" },1–500 字。只创建 requested 申请,不发生资金退款。重复提交返回已有记录;拒绝或失败记录继续保留,不创建第二笔资金请求。

用户可见字段:id、orderId、amount、currency、reason、status、reviewNote、createdAt、updatedAt、succeededAt。时间为 UTC ISO;不返回商户配置、内部渠道错误和补偿状态。

核心用户订单详情页已接入申请和状态面板。自定义订单页面的主题可复用 OrderRefundPanel 或上述接口。

管理接口

统一受管理员登录及现有 orders:view / orders:edit 权限约束。

接口用途
GET /api/admin/orders/refunds?status=requested&page=1&pageSize=20分页队列,不传 status 查询全部;pageSize 最大 100。
GET /api/admin/orders/:id/refund退款详情,含渠道退款号、lastError、effectsStep、effectsError。
POST /api/admin/orders/:id/refund执行以下动作,返回 { data: Refund }。
{ "action": "refund", "reason": "管理员确认整单退款" }
  • refund:无申请时创建并审核执行,创建时必须填写原因。
  • approve:审核通过已有申请并发起原路退款。
  • reject:只可拒绝待审核申请;必填 reason,作为用户可见的 reviewNote。
  • reconcile:查询处理中/结果未知的渠道退款,或重试资金已退后的未完成事项;不会再发一笔退款资金请求。

退款可能影响其他已付订阅周期时返回 409,data.code = "SUBSCRIPTION_REFUND_IMPACT",并给出 impact。管理员核对后可带 confirmSubscriptionImpact: true 重试。

PUT /api/admin/orders/:id 不再接受直接设置 payStatus: refunded,已收款订单不能靠修改支付状态关闭。处于退款流程中的订单禁止普通编辑和后台重新履约;有关联退款记录的订单禁止彻底删除。后台订单页提供申请队列与单笔操作面板。

存量已标记 refunded 但没有退款台账的订单仅作为历史未核实记录保留,不自动生成“渠道资金已退”的证明。应先与商户账单核对再导入可信证据;迁移不会发起退款或伪造历史资金成功记录。这是明确保留的存量核账事项。

状态与恢复

requested → rejected,或 requested → processing → succeeded / failed / unknown。

  • processing 仅表示受理/处理中,不代表资金已退。
  • 网络异常、结果格式错误、身份/金额/币种不符进入 unknown。只向原渠道查单,不切换渠道、不盲目重发退款。
  • 渠道确认失败后保留记录,交由人工核对;不会自动重置或重发,即使渠道幂等保留期已过。
  • 只有确认整单资金退款才将订单标为 refunded。经验证签名并绑定原订单的整单退款回调(含商户平台主动退款)同样进入核心台账;缺失金额、部分金额、原交易号不符均拒绝。
  • 发起时锁定配置/脚本指纹;变更配置后阻断查单,恢复原配置才继续。未决退款期间的凭据轮换须专门核对处理。

后续事项按独立位恢复:effectsStep 中 1 为订单状态、2 为佣金取消、4 为订阅撤销、8 为充值余额回收、16 为通知,v2 新增 32 为扩展资产回收,合计 63 表示全部完成。v1 各位含义保持不变;历史 31 只补新增资产阶段,不重发资金退款、不重复已完成的钱包处理或通知。缺少历史归属/入账证据时保留待核对。余额不足和回收不明仍在台账可见,不制造负余额。订阅撤销投递信息继续保存在订阅元数据。已发放卡密和已下载文件无法收回。

order.refund.assets 是原扩展拥有资产时的独立必达回收钩子,不受 notifyUrl 控制。真实新增支付转移会冻结 orders.metaData.apayRefundAssetPolicy(原归属与扩展回收要求),已付回调重放不能为存量伪造归属策略。扩展加款前先冻结 orders.metaData.apayCreditReceipt:原 operationId、用户/钱包身份、1e8 刻度额度及额度池不可变。历史回收只补查权威原入账回执,不读取当前商品类型或价格。回执及通知只原子更新各自 JSON 路径,保留并发元数据。经鉴权的接收协议可为无本地会员/订阅资产的外部中转载体证明归属;其他存量订单不能一概假设无资产。

中转订单配置专属 notifyUrl 时只发送签名 minimal.checkout.refunded,失败不回退其他通道。其他订单发送 order.refunded,固定 eventId = refund:<refundId>;退款流程会等待已注册的异步主题处理与后台 Webhook 动作完成。响应丢失会导致重复投递,下游必须按事件 ID 幂等;不承诺跨系统严格 exactly-once。

v2 通知载荷增加 refundEffectsVersion: 2。旧事件保留兼容:内置旧充值监听器对 v1 调用仍转交回收,对 v2 通知不重复资产步骤。原归属不匹配或必需回收处理器缺失不能当作成功。

渠道与扩展契约

以下适配随核心产物发布:

支付创建、回调、支付查单及退款统一通过 server/payments/adapters.ts,保留数据库/文件脚本优先级,以及显式命名的旧支付查单配置兼容模式。已编译渠道协议归 server/payments/providers/;原 server/utils/refundProviders.ts、refundAlipay.ts 仅保留兼容导出。v1 退款指纹投影及版本保持不变,迁移源码位置不会锁死未决退款。

  • Stripe:已捕获的 PaymentIntent,或可关联该意向的 Checkout Session;全额退款、幂等请求头、退款元数据与权威查单。不接受仅订阅发票 ID。
  • PayPal:已存的 Checkout 订单、单购买单元/单 capture;锁定全额、PayPal-Request-Id 与 custom_id。响应丢失时尽可能从订单恢复退款号;若渠道无法提供足够匹配证据,保持未知等待人工核对。
  • 微信支付 V3 国内普通商户:仅 CNY,绑定原交易与 out_refund_no,请求签名并验证响应签名。使用已有 mchid、serialNo、privateKey、platformPublicKey、platformSerialNo 配置(兼容 snake_case 别名)。
  • 支付宝国内 OpenAPI(RSA2):仅 CNY,绑定原交易/商户订单和固定 out_request_no。签名调用 alipay.trade.refund 后,必须通过 alipay.trade.fastpay.refund.query 的 REFUND_SUCCESS、本次退款金额和原交易总额确认;累计 refund_fee 和 HTTP 成功均不能单独证明本次成功。使用 alipayPublicKey(兼容别名)对响应原始字节验签;缺失成功状态保持未知。渠道退款引用使用支付宝回传的 out_request_no。

其他渠道需同时提供 payments/<code>/refund.js 和 refund-query.js,未适配时明确阻止执行。仅提供一个脚本不启用退款。部署时须将脚本随支付插件一起打包。可通过 refund-capabilities.json 声明必填配置(key、最小长度、可选 HTTPS URL),核心在一次性资金派发抢占前检查。

签名中转退款(所有源站主题共用)

外置中转支付插件已具备两个退款脚本。源站管理员审核一次,中转 minimal 站验证单独授权的退款客户端后,操作自己的原微信/支付宝交易;不操作源站权益,不替换订单已存的通知地址。

接收端接口:POST /api/minimal/checkout/refund(申请并执行)、POST /api/minimal/checkout/refund-query(只查单)。两者均使用严格请求体:

{"refundId":"rf_源站退款号","orderId":"中转订单号或历史原渠道交易号","externalOrderId":"源站订单号","amount":10,"currency":"USD","reason":"整单退款"}

接收端只定位 source=minimal_checkout + external_order_id 的订单,校验传入引用确为该订单的中转号或原渠道交易号、源金额/币种快照,并要求已存通知地址的来源域名属于退款客户端授权范围。本站钱包、普通 storefront、挂订阅的载体订单不能走此委托。实际渠道退款始终取已存实付金额,例如源站 USD 10 对应收款 CNY 70,退回的就是原收款 CNY 70;校验失败不发资金。

源站支付方式的私有配置须新增 refundClientId、独立 refundSecret(至少 32 字符)、checkoutBaseUrl(HTTPS)。现有 checkoutSecret 不自动获得退款权限。缺配置时在派发前返回 409,申请保留待审核,补配置后可安全操作。

中转站仅在私有运行环境配置(严禁放进公开 domains.env):

MINIMAL_CHECKOUT_REFUND_CLIENTS=[{"id":"source-site","secret":"<新独立随机密钥,至少32字符>","origins":["https://source.example.com","https://source.example.net"]}]

每个源站部署分配独立客户端/密钥及精确 HTTPS 来源白名单,包含其合法多语言域名。未登记时委托关闭,返回 503,不匿名放行。

请求头:X-APay-Refund-Client、X-APay-Refund-Timestamp(13 位毫秒)、X-APay-Refund-Signature(小写 HMAC-SHA256 hex)。请求签名串为 refund:v1\n<clientId>\n<timestamp>\nPOST\n<path>\n<SHA256(rawBody)>,有效偏差五分钟,路径不允许携带 query。响应签名串为 refund-response:v1\n<clientId>\n<timestamp>\n<SHA256(requestRawBody)>\n<responseRawBody>,通过同名 timestamp/signature 响应头返回。源站验证原始响应及退款号、订单、金额、币种后才信任资金结果。

中转端自身也保持一笔订单一个退款台账;重复请求只核对这笔台账,不再发原渠道退款。签名 minimal.checkout.refunded 通知和签名查单结果在源站汇入同一台账。通知失败保留在中转端并独立重试,不切换通知通道。支付插件回调对新订单保留原中转引用,并兼容核对历史保存的原渠道交易号。

部署顺序:核心迁移及中转接收端 → 中转私有客户端登记 → 源站核心/插件及私有凭据 → 商户沙箱/小额验收。回滚前须核对未决记录,未决退款期间不能直接删除原凭据。

全主题覆盖

外部服务额度回收与支付退款分开记账。qingpu 主题注册 order.refund.assets,先通过 AINode GET /api/tenant/users/{userId}/credits/{原operationId} 补查历史原入账,再调用 POST .../{原operationId}/refund;回收不再读取当前商品分类。新逻辑归主题 server/credits/,旧路径仅作兼容转出。网关阻止冻结计划的迟到入账,或返回持久回收/缺口回执。缺口、回执不符、网关未升级、缓存投递不明均保持后续未完成,不会再次触发微信/支付宝退款。部署顺序为先 AINode、后源站;租户预存款独立核对。网关协议见 ainode/docs/ai/tenant-credit-refunds.zh.md。

ainode、qingpu、shopark 自定义详情页嵌入 OrderRefundPanel;其余十个已挂载主题沿用核心详情页。核心与 official 列表在退款后仍保留详情入口;账单/钱包页面可复用 OrderRefundsLink。npm run check:refund-themes 用真实宿主路由解析逐个主题,编译实际面板,并做删除面板必失败的反向探针;不复制十三套退款引擎。

列表守卫同时执行核心/official 模板中的真实状态条件,覆盖已付款、待付款、失败、退款和删除订单。退款订单保留详情链接并展示退款标签,不再误标“已完成”。微信/支付宝共用执行资产与私有商户配置分开管理,前者受版本控制;插件专属公开名称/图标放在 payments/<code>/metadata.json(name、iconUrl 或 iconSvg)并随制品复制,宿主不再静态导入被忽略的支付元数据源码。

npm run check:refund-relay 使用两套真实内存 SQLite 和实际渠道适配器的 RSA/HMAC 桩验证:源币种/实付币种快照、历史交易引用、响应丢失、一次派发、通知独立补偿及凭据/来源域/金额拒绝。npm run check:refund-builds -- --themes minimal,shopark 串行执行指定主题生产构建,每个使用自己的公开构建配置。

脚本沿用可信管理员支付宿主能力,不是真正安全沙箱:

// payload.operation 为 'refund' 或 'query'
// payload.order: { id, amount, currency, tradeNo }
// payload.refund: { id, orderId, amount, currency, reason, providerRefundId }
return {
  status: 'succeeded', // 也支持 pending、failed、unknown
  refundId: payload.refund.id,
  orderId: payload.order.id,
  amount: payload.refund.amount,
  currency: payload.refund.currency,
  providerRefundId: verifiedGatewayRefund.id
}

脚本必须确认原交易、退款身份、币种、全额与权威状态后才返回成功;成功必须有真实渠道退款号。查单脚本只查结果,不得再次转款。渠道错误应返回 unknown 或抛错,不得伪造成功。已有支付回调脚本在输出 status: refunded 前也须完成退款验签及原订单币种绑定。

运维与验收

Node 部署由核心调度器每分钟自动核对;Serverless 必须定时调用 POST /api/cron/process-refunds,携带 Authorization: Bearer <CRON_SECRET>;未配置密钥直接拒绝。数据库租约防止并发资金派发/补偿;过期的退款执行租约只能进入查询。

启用前通过统一迁移器执行新增三方言迁移,不以生产库做测试。回退代码无法撤回已退资金;回滚保留增量台账结构并核对未决退款。未经渠道对账,不可用旧数据库备份覆盖已发生的退款事实。

验收命令:npm run check:refunds、订阅/迁移专项守卫及正常构建。退款专项使用真实临时 SQLite 和外部渠道桩,微信响应验签使用真实 RSA 密钥;不会执行真实资金退款。

协议事实源:Stripe 退款、PayPal capture 退款、微信退款申请、微信退款查询。