退款携带哪些标识，我该向谁报哪一个？
一笔退款最多携带六个标识，三个是你的，三个是 Waffo 的：
如何选择：
- 与 Waffo 支持沟通 →
acquiringRefundOrderId，如果问题涉及原始支付则加上acquiringOrderId。 - 对自己的账 →
merchantRefundOrderId和origPaymentRequestId。这是在你系统内有意义的仅有两个。 - 重试退款 →
refundRequestId，保持不变。新的会创建一笔新退款；这正是该字段的全部意义。 - 与客户沟通 → 以上都不是。客户在自己的支付历史中看到的是原始支付的参考号，它以
payMethodResponse内的payMethodRefId返回在原订单上。如果你需要让第三方找到那笔钱，那才是他们能认出的参考号——见我该看哪些金额和币种字段？。
merchantRefundOrderId 和 refundRequestId 都是 Portal → Transactions → Refunds 中的可见列，因此通过 API 发起的退款可以在 Portal 中按你自己的编号找到，在 Portal 发起的可以按其 Waffo 编号找到。
为什么退款要我填客户的银行账户、姓名或国籍？
因为对于某些支付方式，钱不能简单地沿原路推回——退款是作为向客户的付款执行的，而付款需要支付从未要求过的收款人信息。这是支付方式的属性，不是你账户或单笔退款的属性。 API 在退款请求上把它建模为一个可选的userInfo 对象，在方式要求时变为必填：
**这些值从哪来？**从客户那里。Waffo 不持有客户的银行账户，原始支付也没有——这正是为什么要求填这个字段。实际上这意味着这类方式上的退款不是一键操作：你得先回头向客户索要账户信息，所以请把这一步纳入你的退货流程，而不是在按下 Refund 那一刻才发现。
**你会被告知缺哪些字段，而不用猜。**两个入口的工作方式相同：
- 在 Portal 中，打开退款抽屉会恰好要求该订单需要的字段，银行必须从固定集合中选择时提供可搜索的银行列表，国籍提供国家列表。姓名上限 60 个字符，其他文本字段 64，手机号按支付所在国家的拨号代码校验。中间名是唯一的可选字段。
- 通过 API，缺少必填字段提交的退款会返回告诉你缺哪些字段路径，你可以收集后重新提交。第二轮要求的比第一轮多是正常的——按要求提供并重新提交，而不是预先填满一切。
我把银行账户填错了导致退款失败，能修改那笔退款吗？
不能。退款记录不可编辑，失败的退款上没有”更正并重发”操作。请用新的refundRequestId 和更正后的信息发起一笔新退款。
重新提交前检查两件事：
- **可退金额。**使用退款响应或退款查询中的
remainingRefundAmount，而不是假设失败的尝试释放了全部金额——它是权威数字，并且已经计入了该订单上的每一笔退款。 - **信息本身。**因收款人信息错误而失败的退款，用相同信息会再次失败。请与客户确认账户，而不是从你自己的记录里找。
refundRequestId 也无济于事：它是幂等键，重发它是在索取原来那笔退款，而不是用新信息发起新尝试。幂等重试行为见退款 FAQ。
客户能自己发起退款吗？
**不能。**退款由你发起——通过 Portal 或退款 API——没有面向客户的路径。Waffo 收银台不提供退款操作，客户能到达的订阅自助管理页面也不提供：在那里取消订阅只会停止未来的扣款，不会撤销过去的扣款。 退款记录上的refundSource 以字段形式说明了同一点。它的四个值是：
没有客户值，因为没有客户路径。客户能做的是向其银行发起争议，那是另一套机制，涉及不同的资金和不同的截止时间——见拒付 FAQ。
对你产品的实际影响：如果你想要自助退货，请在你这边构建申请流程，并在你批准时调用退款 API。不要等一个面向客户的 Waffo 页面来引导他们。
我已经自己给客户退过款了，调用退款 API 会让他们收到两次吗？
会。通过 Waffo 发起的退款是真实的资金流动，而 Waffo 对你在平台之外与客户结清的任何事情一无所知——你自己做的银行转账、店铺积分、柜台现金退款。没有任何东西会把两者对上，所以在平台外退款之后再调用退款，会让客户第二次收到钱。 保障措施是退款记录本身，而不是 Waffo 能替你做的检查：- 退款前读取订单的退款历史，在 Portal 中或通过退款查询，并读取
remainingRefundAmount。它告诉你 Waffo 已经发出了什么——包括不是你发起的退款。 - 在你自己的系统中记录平台外的结清，并以此约束你的退款操作。这是该信息唯一存在的地方。
- 在支付方式允许的情况下优先通过 Waffo 退款，正是为了让退款落在与支付相同的记录中。
我能从 Portal 只退部分金额吗？
能。Portal 的退款抽屉打开时预填全部可退金额，且金额字段可编辑：你可以输入大于零且不超过支付金额的任意金额，以订单币种计，并在该币种的小数精度之内。原因是必填的，创建退款之前你要在对话框中确认确切数字。 同一订单上第二次部分退款是否可用是支付方式的问题，不是 Portal 的——有些方式只允许一次部分退款。规划分阶段退款之前请看按支付方式的退款限制，并注意从 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 的通知。
投递到哪里：
事件类型为
REFUND_NOTIFICATION，其 body 与退款查询响应结构相同，所以一个解析器可以同时服务两者。这是刻意的：能读退款查询的集成就能读该 Webhook，轮询是合法的回退而不是第二套实现。
两个运营说明。refundNotifyUrl 上限 256 个字符——比支付的 notifyUrl 短——投递规则与支付 Webhook 相同：标准端口上可达的 HTTPS，以及预期的成功响应 body。投递排查见 Webhook 重试和 Portal Webhook 日志。
我能通过轮询获取退款结果，而不是等 Webhook 吗？
能。/api/v1/refund/inquiry 返回退款的当前状态，是在你未配置通知 URL、验签失败或只是想立刻拿到答案时的正式回退方式。它返回 refundStatus、失败时的 refundFailedReason、refundCompletedAt、remainingRefundAmount 以及完整的标识集。
支付也一样——Order Inquiry 是获取结果的一等方式，不是权宜之计。轮询不能做的是免除处理 Webhook 的需要：构建 Webhook 路径，并用查询来填补空缺，以及回答支持团队”它现在在哪”的问题。
退款多久到达客户？
取决于他们如何支付，诚实的范围很宽。Waffo 的部分——把退款推进到终态——由refundStatus 报告；最后一段掌握在客户的银行、发卡行或钱包提供方手中，Waffo 不承诺到账日期。Portal 的支持页面显示各支付方式的参考处理时间；与客户沟通时以此为参考。即使数字不稳定，答案的形态是稳定的：
如何对客户使用这些信息：
- 退款显示为进行中时，告诉他们退款正在推进；没有需要升级的事。
- 退款显示为已完成、且超过其方式的参考窗口后钱仍未到，值得上报——附上
acquiringRefundOrderId。 - **不要承诺日期。**尤其是卡退款落在账单周期上，不是你能预测的某一天。
退款会把客户支付的手续费和税费退回去吗？
不一定，API 对此很明确：退款时，finalDealAmount——客户收到的金额——可能不含客户原本支付的服务费或税费，这就是为什么它可能小于对应的订单金额。
所以与客户沟通时要分清两个不同的金额：
告诉客户第二个。如果你的政策是连手续费一起补齐，你得自己把它算进去；按订单金额退款不会自动把手续费带回去。
你在原支付上支付的手续费以及商户承担的税费如何处理，是结算问题而不是退款记录问题——见退款 FAQ和手续费与税费处理。
退款原因能写多长，客户能看到吗？
refundReason 在每笔退款上都是必填的。上限取决于你从哪里发起：API 接受最多 256 个字符，Portal 的退款表单把该字段限制在 128，并有实时字数统计。
它是内部注释：随退款记录携带、在 Portal 中显示、在退款查询中返回，是你自己的支持团队六个月后要读的东西。请为那个读者写——订单参考、退货工单号、简短原因——而不是写成给客户的消息。
我在哪里看我的退款，能导出什么？
Portal → Transactions → Refunds 是列表。它的列覆盖完整的标识集加上每笔退款的状态：
列表可按退款标识、状态、币种、Refund Batch ID 和创建时间筛选，并可导出。导出作为后台任务运行，有自己的跨度和大小限制以及自己的状态列表——包括导出成功但失败计数非零的情况——全部见导出中心。交易和退款导出携带哪些列见支付方式配置与限制。
如果你通过 API 发起的退款不在列表中，在断定它丢失之前先按你自己的
refundRequestId 或 merchantRefundOrderId 搜索——那些是列，退款可以按你自己的编号找到。
退款显示成功，但客户说钱从未到账
按以下顺序排查，因为三种不同的情况会产生同样的投诉：- 检查其支付方式的参考窗口（Portal 的支持页面显示它）。尚未到下一个账单周期的卡退款不算迟。
- 检查
finalDealAmount，而不是refundAmount。如果手续费未退回，客户收到的比预期少，可能把这读成”没到”。 - **检查钱发到了哪里。**退到钱包余额的方式上，钱进的是钱包而不是背后的卡——查看卡账单的客户不会看到它。
acquiringRefundOrderId 和日期。报告成功但在下游失败的退款，以及以 ORDER_REFUND_FAILED 结束的退款，见按支付方式的退款限制。
给稳定币支付退款有自己的必填字段——同链上的接收地址——以及关于谁支付网络费用的规则；见稳定币异常。
需要追踪一笔退款？请联系支持，附上
acquiringRefundOrderId。