Skip to main content
本页解答商户关于退款最常问的问题。 字段级契约见收单 API 规范 （/api/v1/order/refund、/api/v1/refund/inquiry、退款订单通知）。

​
同一笔订单可以退款多次吗？

取决于支付方式和您的合同配置：
  • 支持多次部分退款——每次退款都会校验 已退款 + 处理中 + 本次请求 ≤ 原支付金额。生产环境 单笔订单最多允许 50 次退款；超出后返回 错误 A0027。Sandbox 和测试环境的上限更低，所以在那里 仅几次退款后就遇到 A0027 是正常现象，不是 bug。每个退款响应都包含 remainingRefundAmount，方便您 跟踪仍可退款的金额。
  • 不支持——订单完成一次退款后，任何 后续退款请求都会被拒绝。
每次成功的部分退款都会把订单的退款状态 （refundStatus）置为 ORDER_PARTIALLY_REFUNDED；只有当成功退款的总金额等于 订单金额时才变为 ORDER_FULLY_REFUNDED。订单的 orderStatus 本身不会因退款而改变—— 已全额退款的订单仍然显示 PAY_SUCCESS。

​
我的退款为什么被拒绝了？

退款请求必须通过以下所有前置条件： 有效期和多次退款支持 取决于合同——请在商户 Portal 中查看您的合同，或联系 集成支持了解您的确切配置。

​
我的退款请求超时了，可以安全地重发吗？

可以。refundRequestId 是幂等键：
  • 用相同 ID 和相同金额重发会返回当前退款 状态；如果退款仍处于中间状态，会推进处理。
  • 用相同 ID 但不同金额重发会被拒绝。
要安全重试，请始终重发完全相同的请求。只有在您打算创建额外一笔退款时， 才使用新的 refundRequestId。

​
跨币种退款金额是怎么计算的？

当用户以不同于您订单币种的币种支付时，您提交的 退款金额（订单币种）会换算为用户的 币种。适用两条规则：
  • 向下取整——换算后的退款金额始终向下取整，因此 退款总额永远不会超过用户实际支付的金额。
  • 最后一笔补齐——多次部分退款时，汇率取整可能 让退款总额略低于支付金额。耗尽剩余余额的最后一笔 退款会返还全部余额，因此 全额退款的订单确实能到达 ORDER_FULLY_REFUNDED。
退款查询响应中的 finalDealAmount 是用户以其币种 实际收到的金额。

​
我取消了订单，但用户说已经付款了

取消只对仍处于中间状态的订单有效。如果 用户实际上已完成支付，取消请求会失败， 订单按支付成功继续——您会收到支付成功 通知。此时要退回资金，请使用退款 API；不要 重试取消。

​
退款要多久？状态一直是处理中

退款是异步的。/api/v1/order/refund 调用成功表示 请求已被接受（REFUND_IN_PROGRESS），不表示已完成。随后 Waffo 与支付方式处理退款，并对可恢复的失败自动重试， 直到到达最终状态。
  • 提供 refundNotifyUrl 以通过退款 订单通知接收最终结果，或轮询 /api/v1/refund/inquiry。
  • 只有在 ORDER_PARTIALLY_REFUNDED、 ORDER_FULLY_REFUNDED 或 ORDER_REFUND_FAILED 时退款才是最终态——请把 REFUND_IN_PROGRESS 视为待处理，而不是失败。

​
所有支付方式都支持 API 退款吗？

不是，并且有两种不同的情形。 **不允许退款。**两个错误码，两种含义。A0017（“payment channel not supported”）表示支付方式本身无法承载退款——无论全额还是 部分。A0014（“refund rules”）表示该方式可以退款，但您 协议的退款形态不允许这一次请求：在仅允许全额退款的行上发起 部分退款，或在仅允许一次退款时发起第二次退款。请求 超过剩余可退金额则是第三种情形——普通的 A0003 参数错误。见 各支付方式退款限制。 **需要额外字段的退款。**有些退款需要额外的用户 信息，例如银行账户信息，因为资金是通过 转账退回而不是在原支付上冲正。**需要哪些字段 按通道配置，所以不要在您自己的代码中根据支付 方式来判断。**先提交退款；如果缺少字段，API 返回 A0003 并附上缺失字段名列表，您补齐这些字段后 重发即可。 对于某些支付方式，退款在 Waffo 侧通过 Payout 通道执行—— 您的 API 契约保持不变。

​
我可以一次提交很多笔退款吗？

可以——Portal 交易模块下的批量退款页面。它 按商户账户启用，所以如果该页面不存在，说明尚未为您 开通；请联系支持团队。模板和上传按钮仅对 已能发起单笔退款的角色可见。 流程是：导出批量退款模板（CSV），填写，上传， 确认汇总对话框（记录数、总金额、币种），然后 Waffo 创建一个 Refund Batch ID，格式为 BRP + MID + YYYYMMDD + 6 位 序号——例如 BRP<your merchant ID>20260225000001。

​
我整个批量文件被拒了，为什么？

上传校验是全有或全无：一行出错就拒绝整个文件， 您修正后重新上传即可。校验内容：
  • 文件——必须是导出的 CSV 模板，恰好包含其四 列且无多余列；未损坏、未加密、非空；最多 2,000 条记录和 2 MB；且不是之前已上传过的文件 （重复通过文件内容而非文件名检测）。
  • 币种——整个文件只能有一个退款币种，且必须等于 每笔原订单的币种。
  • 每一行——原订单存在、已支付且尚未全额 退款、其支付方式允许退款、仍在退款 有效期内、金额大于零且不超过剩余可退 金额，且该订单没有正在处理中的退款。
  • 重复——同一订单不能在一个批次中出现两次。
  • 批次总额——文件总额必须能被您上传时的 待结算余额加退款备用金余额覆盖。
逐行规则与单笔退款通过的前置条件相同；各条含义 见上文”我的退款为什么被拒绝了？“。

​
提交批次后怎么跟踪？

各行独立处理：失败的行会标注原因， 其余继续——一行失败不会停止整个批次。 批次列表显示总数 / 成功 / 失败 / 处理中的计数、批次 金额和币种，以及创建和更新时间。每笔退款都带有 其 Refund Batch ID，因此您可以按批次筛选退款列表，照常打开任何 单笔退款的详情，并导出包含 失败原因的批次结果。批次没有重试操作——请把失败的 行放到新文件中重新提交，或逐笔退款。

​
部分退款时原支付手续费会退回吗？

默认是退款不退手续费。如果您的合同包含 手续费退回，退款会按比例退回原支付手续费的对应部分， 向下取整到 2 位小数：
部分退款按比例退回，全额退款全部退回。 由于规则是向下取整，退回的手续费可能比直接按比例计算的 数字少一分钱。它作为退款行 Settlement Amount 中的一个正向 组成部分出现——见 结算报表与导出。