> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 退款 FAQ

> 解答关于 Waffo 退款最常见的问题：多次部分退款、退款前置条件、幂等重试、跨币种金额与取整、退款与取消的区别、处理时长以及支付方式限制。

本页解答商户关于退款最常问的问题。
字段级契约见收单 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`。

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

退款请求必须通过以下所有前置条件：

| 前置条件 | 说明 |
| - | - |
| 订单状态 | 原支付必须成功。 |
| 合同支持退款 | 退款能力是合同设置；对不可退款合同发起的请求会失败（例如 `A0014`）。 |
| 退款有效期 | 仅在合同定义的期限内接受退款，该期限从**订单创建日期**（不是支付成功）起算，至最后一天结束。请查看订单查询响应中的 `refundExpiryAt`——不允许退款时为 `null`。 |
| 资金充足 | Waffo 首先从您的待结算余额（可用余额，含任何透支额度）中扣除退款。若不足，则回退到您的退款备用金账户。只有两者都无法覆盖时，请求才会以 `A0012` 被拒绝。 |
| 无未结争议 | 处于拒付争议中的订单会被锁定不可退款（`A0019`）。已被拒付预警服务退款的订单返回 `A0039`。 |

有效期和多次退款支持
取决于合同——请在商户 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` 参数错误。见
[各支付方式退款限制](/docs/zh/support/payment-method-refund-limits-faq)。

\*\*需要额外字段的退款。\*\*有些退款需要额外的用户
信息，例如银行账户信息，因为资金是通过
转账退回而不是在原支付上冲正。\*\*需要哪些字段
按通道配置，所以不要在您自己的代码中根据支付
方式来判断。\*\*先提交退款；如果缺少字段，API
返回 `A0003` 并附上缺失字段名列表，您补齐这些字段后
重发即可。

对于某些支付方式，退款在 Waffo 侧通过 Payout 通道执行——
您的 API 契约保持不变。

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

可以——Portal 交易模块下的**批量退款**页面。它
按商户账户启用，所以如果该页面不存在，说明尚未为您
开通；请联系支持团队。模板和上传按钮仅对
已能发起单笔退款的角色可见。

流程是：导出批量退款模板（CSV），填写，上传，
确认汇总对话框（记录数、总金额、币种），然后 Waffo
创建一个 **Refund Batch ID**，格式为 `BRP` + MID + `YYYYMMDD` + 6 位
序号——例如 `BRP<your merchant ID>20260225000001`。

| 模板列 | 必填 |
| - | - |
| Original Order Id | 是 |
| Refund Amount | 是 |
| Refund Currency | 是 |
| Refund Reason | 否 |

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

上传校验是全有或全无：一行出错就拒绝整个文件，
您修正后重新上传即可。校验内容：

* **文件**——必须是导出的 CSV 模板，恰好包含其四
  列且无多余列；未损坏、未加密、非空；最多
  **2,000 条记录**和 **2 MB**；且不是之前已上传过的文件
  （重复通过文件内容而非文件名检测）。
* **币种**——整个文件只能有一个退款币种，且必须等于
  每笔原订单的币种。
* **每一行**——原订单存在、已支付且尚未全额
  退款、其支付方式允许退款、仍在退款
  有效期内、金额大于零且不超过剩余可退
  金额，且该订单没有正在处理中的退款。
* **重复**——同一订单不能在一个批次中出现两次。
* **批次总额**——文件总额必须能被您上传时的
  待结算余额加退款备用金余额覆盖。

逐行规则与单笔退款通过的前置条件相同；各条含义
见上文"我的退款为什么被拒绝了？"。

## 提交批次后怎么跟踪？

各行独立处理：失败的行会标注原因，
其余继续——一行失败不会停止整个批次。

| 批次状态 | 含义 |
| - | - |
| `INIT` | 批次已创建，尚未开始处理 |
| `PROCESSING` | 至少还有一行在处理中 |
| `PARTIAL_SUCCESS` | 部分行成功，部分行失败 |
| `FULL_SUCCESS` | 所有行成功 |
| `FAILED` | 所有行失败 |

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

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

默认是**退款不退手续费**。如果您的合同包含
手续费退回，退款会按比例退回原支付手续费的对应部分，
**向下**取整到 2 位小数：

```
Returned fee = ROUNDDOWN2( refund amount / original order amount × original fee amount )
```

部分退款按比例退回，全额退款全部退回。
由于规则是向下取整，退回的手续费可能比直接按比例计算的
数字少一分钱。它作为退款行 Settlement Amount 中的一个正向
组成部分出现——见
[结算报表与导出](/docs/zh/support/settlement-reports-faq)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.