> ## 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.

# 退款记录、ID、通知与时效

> 退款携带的每个标识以及该向谁报哪一个、为什么有些退款要求你提供客户的银行账户和姓名、这些信息填错了怎么办、退款 Webhook 何时触发以及发到哪里、退款通常多久到达客户，以及客户能否自己发起退款。

退款是否*被允许*在其他页面介绍；本页讲的是退款**记录**——它的标识、某些退款要求你提供的额外信息、你如何得知结果，以及该对等待中的客户说什么。

| 页面 | 用途 |
| - | - |
| [退款 FAQ](/docs/zh/support/refund-faq) | 核心规则、跨币种金额、安全重试 |
| [按支付方式的退款限制](/docs/zh/support/payment-method-refund-limits-faq) | 多少次、多少钱、截止何时，以及各方式的差异 |
| [退款资金从哪里来](/docs/zh/support/refund-funding-source-faq) | 余额、资金不足、对结算的影响 |
| [批量退款](/docs/zh/support/batch-refund-faq) | CSV 流程和批次跟踪 |
| **本页** | ID、额外收款人字段、通知、时效、导出 |

## 退款携带哪些标识，我该向谁报哪一个？

一笔退款最多携带六个标识，三个是你的，三个是 Waffo 的：

| 字段 | 谁生成 | 标识什么 |
| - | - | - |
| `refundRequestId` | **你**（最长 32） | 这次退款**请求**。它是幂等键——复用它可安全地重试同一笔退款 |
| `merchantRefundOrderId` | **你**（最长 64） | 你自己的退款订单号，供你记账 |
| `acquiringRefundOrderId` | **Waffo** | 退款订单。**这是向 Waffo 支持报的那一个** |
| `acquiringOrderId` | **Waffo** | 被退款的**原始支付** |
| `origPaymentRequestId` | **你**，在原始支付上 | 你对原始支付的请求 id——退款借此关联回你自己的支付记录 |
| Refund Batch ID | **Waffo** | 仅对从批量文件创建的退款存在——见[批量退款](/docs/zh/support/batch-refund-faq) |

如何选择：

* **与 Waffo 支持沟通** → `acquiringRefundOrderId`，如果问题涉及原始支付则加上 `acquiringOrderId`。
* **对自己的账** → `merchantRefundOrderId` 和 `origPaymentRequestId`。这是在你系统内有意义的仅有两个。
* **重试退款** → `refundRequestId`，保持不变。新的会创建一笔新退款；这正是该字段的全部意义。
* **与客户沟通** → 以上都不是。客户在自己的支付历史中看到的是*原始支付*的参考号，它以 `payMethodResponse` 内的 `payMethodRefId` 返回在原订单上。如果你需要让第三方找到那笔钱，那才是他们能认出的参考号——见[我该看哪些金额和币种字段？](/docs/zh/support/order-amount-and-currency-fields-faq)。

`merchantRefundOrderId` 和 `refundRequestId` 都是 Portal → Transactions → Refunds 中的可见列，因此通过 API 发起的退款可以在 Portal 中按你自己的编号找到，在 Portal 发起的可以按其 Waffo 编号找到。

## 为什么退款要我填客户的银行账户、姓名或国籍？

因为对于某些支付方式，钱不能简单地沿原路推回——退款是作为向客户的付款执行的，而付款需要支付从未要求过的收款人信息。这是支付方式的属性，不是你账户或单笔退款的属性。

API 在退款请求上把它建模为一个可选的 `userInfo` 对象，在方式要求时变为必填：

| 分组 | 字段 |
| - | - |
| 银行信息 | `userInfo.userBankInfo.bankAccountNo`、`bankCode`、`bankName`、`bankCity`、`bankBranch` |
| 身份 | `userInfo.userType`（`INDIVIDUAL` / `BUSINESS`）、`userFirstName`、`userMiddleName`、`userLastName`、`nationality` |
| 联系方式 | `userInfo.userEmail`、`userInfo.userPhone`（`+CountryCode-Number`） |
| 证件 | `userInfo.userIDType`、`userIDNumber`、`userIDIssueDate`、`userIDExpiryDate`（日期格式 `dd/mm/yyyy`） |

\*\*这些值从哪来？\*\*从客户那里。Waffo 不持有客户的银行账户，原始支付也没有——这正是为什么要求填这个字段。实际上这意味着这类方式上的退款不是一键操作：你得先回头向客户索要账户信息，所以请把这一步纳入你的退货流程，而不是在按下 Refund 那一刻才发现。

\*\*你会被告知缺哪些字段，而不用猜。\*\*两个入口的工作方式相同：

* **在 Portal 中**，打开退款抽屉会恰好要求该订单需要的字段，银行必须从固定集合中选择时提供可搜索的银行列表，国籍提供国家列表。姓名上限 60 个字符，其他文本字段 64，手机号按支付所在国家的拨号代码校验。中间名是唯一的可选字段。
* **通过 API**，缺少必填字段提交的退款会返回告诉你缺哪些字段路径，你可以收集后重新提交。第二轮要求的比第一轮多是正常的——按要求提供并重新提交，而不是预先填满一切。

一般机制以及字段路径所用的记法见[按支付方式的条件必填字段](/docs/zh/support/conditional-required-fields-faq)。

## 我把银行账户填错了导致退款失败，能修改那笔退款吗？

不能。退款记录不可编辑，失败的退款上没有"更正并重发"操作。请用**新的 `refundRequestId`** 和更正后的信息发起一笔**新退款**。

重新提交前检查两件事：

* \*\*可退金额。\*\*使用退款响应或退款查询中的 `remainingRefundAmount`，而不是假设失败的尝试释放了全部金额——它是权威数字，并且已经计入了该订单上的每一笔退款。
* \*\*信息本身。\*\*因收款人信息错误而失败的退款，用相同信息会再次失败。请与客户确认账户，而不是从你自己的记录里找。

复用*相同的* `refundRequestId` 也无济于事：它是幂等键，重发它是在索取原来那笔退款，而不是用新信息发起新尝试。幂等重试行为见[退款 FAQ](/docs/zh/support/refund-faq)。

## 客户能自己发起退款吗？

\*\*不能。\*\*退款由你发起——通过 Portal 或退款 API——没有面向客户的路径。Waffo 收银台不提供退款操作，客户能到达的订阅自助管理页面也不提供：在那里取消订阅只会停止未来的扣款，不会撤销过去的扣款。

退款记录上的 `refundSource` 以字段形式说明了同一点。它的四个值是：

| `refundSource` | 含义 |
| - | - |
| `MERCHANT` | 你发起的 |
| `RDR` | 由拒付预警服务自动发起 |
| `ETHOCA` | 由拒付预警服务自动发起 |
| `CDRN` | 由拒付预警服务自动发起 |

没有客户值，因为没有客户路径。客户*能*做的是向其银行发起争议，那是另一套机制，涉及不同的资金和不同的截止时间——见[拒付 FAQ](/docs/zh/support/chargeback-faq)。

对你产品的实际影响：如果你想要自助退货，请在你这边构建申请流程，并在你批准时调用退款 API。不要等一个面向客户的 Waffo 页面来引导他们。

## 我已经自己给客户退过款了，调用退款 API 会让他们收到两次吗？

会。通过 Waffo 发起的退款是真实的资金流动，而 Waffo 对你在平台之外与客户结清的任何事情一无所知——你自己做的银行转账、店铺积分、柜台现金退款。没有任何东西会把两者对上，所以在平台外退款之后再调用退款，会让客户第二次收到钱。

保障措施是退款记录本身，而不是 Waffo 能替你做的检查：

* **退款前读取订单的退款历史**，在 Portal 中或通过退款查询，并读取 `remainingRefundAmount`。它告诉你 Waffo 已经发出了什么——包括不是你发起的退款。
* **在你自己的系统中记录平台外的结清**，并以此约束你的退款操作。这是该信息唯一存在的地方。
* **在支付方式允许的情况下优先通过 Waffo 退款**，正是为了让退款落在与支付相同的记录中。

同样的逻辑反过来也成立：Waffo 已经退款的订单不需要你再做第二次动作，在平台外再次付给客户是镜像的错误。

## 我能从 Portal 只退部分金额吗？

能。Portal 的退款抽屉打开时预填全部可退金额，且金额字段可编辑：你可以输入**大于零且不超过**支付金额的任意金额，以订单币种计，并在该币种的小数精度之内。原因是必填的，创建退款之前你要在对话框中确认确切数字。

同一订单上*第二次*部分退款是否可用是支付方式的问题，不是 Portal 的——有些方式只允许一次部分退款。规划分阶段退款之前请看[按支付方式的退款限制](/docs/zh/support/payment-method-refund-limits-faq)，并注意从 Portal 退款的稳定币订单还额外需要原链上的接收地址。

## 退款记录显示 `RDR`、`ETHOCA` 或 `CDRN`，我还能给这个订单退款吗？

该订单已经被自动退款，以阻止预警服务预见到的争议。因此：

* \*\*该订单上不再有可用的退款。\*\*一旦订单带有由拒付预警服务发起的未失败退款，之后的每一次退款尝试都会以专用错误拒绝——`A0039 Order has already been refunded by chargeback alert service`——**无论金额多少**。该检查不看自动退款是否覆盖了全部支付，所以这类订单上 `remainingRefundAmount` 大于零并不意味着你可以通过 API 或 Portal 退剩余部分。如果你认为仍欠客户款项，那是支持案例。
* \*\*不要假设自动退款没有发生而在 Waffo 之外再次给客户退款。\*\*先读退款记录——`refundSource` 就是为此存在的。

处于活跃争议中的订单被单独阻止退款，有自己的错误（`A0019`）。这个区分很重要：`A0039` 意味着*已退款*，`A0019` 意味着*争议进行期间被锁定*。两者都不能原样重试。

## 退款 Webhook 何时触发，发到哪里？

在退款到达**终态**——完成或失败——时触发。没有中间的"退款已接受"Webhook，所以你不会收到 `REFUND_IN_PROGRESS` 的通知。

投递到哪里：

| 情况 | 目标 |
| - | - |
| 退款请求上发送了 `refundNotifyUrl` | 该 URL |
| 未发送，但你的账户配置了退款通知 URL | 配置的 URL |
| 两者都没有 | 无 Webhook。用 `/api/v1/refund/inquiry` 获取结果 |
| 从批量文件创建的退款 | 配置的账户 URL——批次行不携带按行 URL |

事件类型为 `REFUND_NOTIFICATION`，其 body 与退款查询响应结构相同，所以一个解析器可以同时服务两者。这是刻意的：能读退款查询的集成就能读该 Webhook，轮询是合法的回退而不是第二套实现。

两个运营说明。`refundNotifyUrl` 上限 256 个字符——比支付的 `notifyUrl` 短——投递规则与支付 Webhook 相同：标准端口上可达的 HTTPS，以及预期的成功响应 body。投递排查见 [Webhook 重试](/docs/zh/developer-docs/webhook/retry)和 [Portal Webhook 日志](/docs/zh/support/portal-webhook-log-faq)。

## 我能通过轮询获取退款结果，而不是等 Webhook 吗？

能。`/api/v1/refund/inquiry` 返回退款的当前状态，是在你未配置通知 URL、验签失败或只是想立刻拿到答案时的正式回退方式。它返回 `refundStatus`、失败时的 `refundFailedReason`、`refundCompletedAt`、`remainingRefundAmount` 以及完整的标识集。

支付也一样——Order Inquiry 是获取结果的一等方式，不是权宜之计。轮询不能做的是免除处理 Webhook 的需要：构建 Webhook 路径，并用查询来填补空缺，以及回答支持团队"它现在在哪"的问题。

## 退款多久到达客户？

取决于他们如何支付，诚实的范围很宽。Waffo 的部分——把退款推进到终态——由 `refundStatus` 报告；最后一段掌握在客户的银行、发卡行或钱包提供方手中，Waffo 不承诺到账日期。Portal 的支持页面显示各支付方式的参考处理时间；与客户沟通时以此为参考。即使数字不稳定，答案的形态是稳定的：

| 客户如何支付 | 预期 |
| - | - |
| 信用卡或借记卡 | 最慢的路径——退款落在发卡行设定的账单周期上，而不是任何人能预测的某一天 |
| 网银或银行转账 | 以工作日而非小时计，因银行和国家而异 |
| 钱包——退到钱包余额 | 通常很快，常常当天 |
| 钱包——以其他方式退款 | 以工作日计，因钱包或银行而异 |
| 手工转账、ATM 或现金存款 | 以工作日计，受银行和国家影响 |

如何对客户使用这些信息：

* **退款显示为进行中时**，告诉他们退款正在推进；没有需要升级的事。
* **退款显示为已完成**、且超过其方式的参考窗口后钱仍未到，值得上报——附上 `acquiringRefundOrderId`。
* \*\*不要承诺日期。\*\*尤其是卡退款落在账单周期上，不是你能预测的某一天。

某种方式上是否*能够*退款，以及各方式的退款截止时间，是另一个问题——见[按支付方式的退款限制](/docs/zh/support/payment-method-refund-limits-faq)。

## 退款会把客户支付的手续费和税费退回去吗？

不一定，API 对此很明确：退款时，`finalDealAmount`——*客户收到的金额*——可能**不含**客户原本支付的服务费或税费，这就是为什么它可能小于对应的订单金额。

所以与客户沟通时要分清两个不同的金额：

| 字段 | 是什么 |
| - | - |
| `refundAmount` | 你要求退的金额，以订单币种计 |
| `finalDealAmount` | 客户实际收到的金额 |

告诉客户第二个。如果你的政策是连手续费一起补齐，你得自己把它算进去；按订单金额退款不会自动把手续费带回去。

**你**在原支付上支付的手续费以及商户承担的税费如何处理，是结算问题而不是退款记录问题——见[退款 FAQ](/docs/zh/support/refund-faq)和[手续费与税费处理](/docs/zh/support/fee-and-tax-treatment-faq)。

## 退款原因能写多长，客户能看到吗？

`refundReason` 在每笔退款上都是**必填**的。上限取决于你从哪里发起：API 接受最多 **256** 个字符，Portal 的退款表单把该字段限制在 **128**，并有实时字数统计。

它是内部注释：随退款记录携带、在 Portal 中显示、在退款查询中返回，是你自己的支持团队六个月后要读的东西。请为那个读者写——订单参考、退货工单号、简短原因——而不是写成给客户的消息。

## 我在哪里看我的退款，能导出什么？

Portal → Transactions → **Refunds** 是列表。它的列覆盖完整的标识集加上每笔退款的状态：

| 分组 | 列 |
| - | - |
| 标识 | 退款订单 id、原订单 id、你的退款订单 id、你的原订单 id、退款请求 id、Refund Batch ID、子商户 id（如你使用） |
| 金额 | 退款金额和币种 |
| 方式 | 支付方式、类型和国家、掩码卡号 |
| 状态 | 退款状态、结算状态 |
| 时间 | 创建日期和时间、原支付日期和时间 |
| 关联 | 关联的订阅 id、你的用户 id |

列表可按退款标识、状态、币种、Refund Batch ID 和创建时间筛选，并可导出。导出作为后台任务运行，有自己的跨度和大小限制以及自己的状态列表——包括导出成功但失败计数非零的情况——全部见[导出中心](/docs/zh/support/export-center-faq)。交易和退款导出携带哪些列见[支付方式配置与限制](/docs/zh/support/payment-method-config-and-limits-faq)。

如果你通过 API 发起的退款不在列表中，在断定它丢失之前先按你自己的 `refundRequestId` 或 `merchantRefundOrderId` 搜索——那些是列，退款可以按你自己的编号找到。

## 退款显示成功，但客户说钱从未到账

按以下顺序排查，因为三种不同的情况会产生同样的投诉：

1. **检查其支付方式的参考窗口**（Portal 的支持页面显示它）。尚未到下一个账单周期的卡退款不算迟。
2. **检查 `finalDealAmount`**，而不是 `refundAmount`。如果手续费未退回，客户收到的比预期少，可能把这读成"没到"。
3. \*\*检查钱发到了哪里。\*\*退到钱包余额的方式上，钱进的是钱包而不是背后的卡——查看卡账单的客户不会看到它。

如果三项都没问题而钱仍然缺失，那是支持案例：发送 `acquiringRefundOrderId` 和日期。报告成功但在下游失败的退款，以及以 `ORDER_REFUND_FAILED` 结束的退款，见[按支付方式的退款限制](/docs/zh/support/payment-method-refund-limits-faq)。

给稳定币支付退款有自己的必填字段——同链上的接收地址——以及关于谁支付网络费用的规则；见[稳定币异常](/docs/zh/support/stablecoin-exceptions-faq)。

***

需要追踪一笔退款？请[联系支持](mailto:support@waffo.com)，附上 `acquiringRefundOrderId`。


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