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

# 稳定币异常与退款

> 购物者多付、少付、迟付，或在错误的链上、用错误的代币支付时会发生什么——这些情况您在哪里能看、哪里看不到，USDC/USDT 退款必须使用的确切地址格式，以及为什么稳定币退款是全有或全无。

稳定币支付未按预期到账时会发生什么，以及当*您*退款一笔 USDC 或 USDT 订单时
必须发送什么。订单字段、链的选择
和确认行为见[稳定币支付](/docs/zh/support/stablecoin-payments-faq)；
所有支付方式通用的规则见[退款 FAQ](/docs/zh/support/refund-faq)。

## 有哪些异常情形？订单还能成功吗？

Waffo 会把不符合规范的转账归入以下情形之一——您提交工单时，支持团队使用的就是这些标签。

| 情形 | 发生了什么 | 订单成功？ | 资金去向 |
| - | - | - | - |
| `OVERPAID` | 收到金额高于订单金额 | 是 | 按订单金额给您结算；多出部分退回付款地址 |
| `UNDERPAID` | 收到金额低于订单金额 | 否 | 退回付款地址 |
| `LATE_PAID` | 转账在支付窗口关闭后到达 | 否 | 退回付款地址 |
| `WRONG_TOKEN` | 发送了订单 USDC/USDT 之外的代币 | 否 | 留待人工处理 |
| `WRONG_CHAIN` | 在订单指定链之外的链上发送 | 否 | 留待人工处理 |
| `NO_MATCH_ORDER` | 转账无法关联到任何订单 | 否 | 留待人工处理 |
| `UNSUPPORTED_WALLET_ADDRESS` | 付款地址无法接收自动退回 | 视上述情形而定 | 留待人工处理 |

表格贯穿两条规则：结算始终基于**订单
金额**，绝不基于实际转账金额；向购物者退回资金
不是您账户上的退款——没有退款订单，也不会出现在您的退款报表里。

## 购物者多付了——多出来的归我吗？

不。订单按订单金额完成，多出部分不属于您。小额
溢出——在订单金额的容差范围内，或小于
退回它的成本——不会退回，也不会记入您的账户；较大的
溢出会退回付款地址，扣除该转账成本。所以永远不要
用链上金额来核对稳定币订单。

## 购物者少付了或付晚了——我还能发货吗？

不能。两种情形都不算支付成功，所以不要凭您自己观察到的
链上转账发货。Waffo 会把收到的金额扣除转账成本后退回
付款地址；如果不足以覆盖该成本，则不
退回任何金额。请引导购物者在支付页面的支付窗口内，
一次转账付足全部订单金额。

## 链错了、代币错了、或者用了旧地址——会自动解决吗？

不会。`WRONG_TOKEN`、`WRONG_CHAIN` 和 `NO_MATCH_ORDER` 永远不会自动
处理：订单不会成功，资金也不会自行
退回。请携交易哈希、链、代币和订单 id 提交支持工单。
`NO_MATCH_ORDER` 的常见原因是复用了收款地址——地址是
按订单签发的，所以如果您缓存了地址或让购物者付了两次，第二笔
转账不会匹配任何订单。

## 购物者从交易所付款时，为什么退回很慢？

自动退回只会发到自托管钱包（EOA）。从
交易所提币地址或合约地址发出的资金无法安全地退回
原地址——该地址不是购物者本人的——因此该情形进入人工
处理，耗时明显更长。在可能的情况下，请告知购物者从
自己的钱包付款，而不是直接从交易所账户付款。

## 我自己在哪里能看到这些异常情形？

Portal 里任何地方都看不到，这是实话而不是缺了一个
页面：没有任何面向商户的视图携带链上详情。交易列表和
交易详情没有链的列、没有交易哈希、没有确认
数，也没有收到金额与订单金额的对比，因此多付、
少付或错链转账不是您能查到的内容。

您能看到的是**订单**：它要么到达了最终成功状态，要么
没有。上述一切说的是资金去了哪里，而不是
订单，并且这些情形都不会在您账户上创建退款订单——所以
它们也永远不会出现在您的退款列表或退款报表中。

于是当购物者坚称已付款时只剩一条路：把订单 id 连同
购物者能提供的交易哈希、链和代币一起提交给
支持团队。这四项事实就是识别该情形的依据。

唯一的例外是 x402 签名路径，成功的订单会在 API 上返回
链上结算回执，包含交易哈希——见
[x402 稳定币收单](/docs/zh/developer-docs/use-cases/x402-stablecoin-acquiring)。

## 退款稳定币订单时我必须发送什么？

每笔 USDC 和 USDT 退款都必须填写退款目标地址。请把地址放在
`/api/v1/order/refund` 的 `extendInfo` 里。外层 `extendInfo` 的值是一个
包含 JSON 的字符串，不是嵌套的 JSON 对象。

下面是完整的请求体示例。请把每个占位值替换为订单和购物者的实际值：

```json theme={null}
{
  "refundRequestId": "refund_20261008_001",
  "acquiringOrderId": "<acquiringOrderId>",
  "merchantId": "<merchantId>",
  "requestedAt": "2026-10-08T14:30:00.000Z",
  "refundAmount": "10.00",
  "refundReason": "Customer requested a refund",
  "extendInfo": "{\"refundAddress\":\"<customerRefundAddress>\"}"
}
```

`refundAmount` 必须填写订单的全部可退金额。退款地址必须适用于原支付
使用的链。省略地址时，请求会在前置参数校验时失败——`A0003`，错误信息为
`Parameter validation failed ( missing refund optional field )`。
`msgParams.missingFields` 中会包含 `extendInfo.refundAddress`。此时**不会创建
退款订单**，之后也没有可查询的内容；对法币订单它是不必要的，传了会被忽略。
请把这当作一次集成变更：
如果您已经在调用退款 API，之后又接入稳定币，请先更新您的
退款路径。请自行向购物者收集地址——Waffo 无法
联系您的购物者索要。

## 我能退到另一条链，或者任意钱包吗？

两者都不行。链从原支付读取并锁定；退款请求上没有
链参数，任何试图传入的都会被忽略。
链决定接受哪种地址格式，退款处理时会按
该链的格式校验地址：

| 地址族 | 接受的格式 | 同时拒绝 |
| - | - | - |
| EVM 链（Ethereum、Polygon、Arbitrum、Base、Optimism、Avalanche、BNB Smart Chain） | `0x` 后跟 40 个十六进制字符 | 全零地址。在 Avalanche 上，X-Chain 和 P-Chain 地址——必须是 C-Chain EVM 地址 |
| Solana | 32–44 个 Base58 字符，区分大小写 | — |
| Tron | `T` 后跟 33 个 Base58 字符，带校验和 | 校验和无法验证的地址 |

两个格式细节值得写进您自己的输入校验，因为它们
确实会被检查，而且常常让人意外：

* \*\*大小写混合的 EVM 地址会做校验和验证（EIP-55）。\*\*全部
  小写或全部大写的地址原样接受；大小写
  混合的地址必须有有效的 EIP-55 校验和。所以一个被手工"整理"过——
  改了一个字母大小写——的地址会失败，而同一地址全部小写
  则通过。
* **Tron 地址会做 Base58Check 解码**，不只是模式匹配。
  一个打错的字符会在校验和上失败，而不是先被接受
  再在链上失败。

被拒绝的地址会以
`INVALID_REFUND_ADDRESS_FORMAT` 开头的信息失败，后跟具体原因。与
*缺失*地址不同，*格式错误*的地址在后一步才被捕获——在退款
订单已经创建之后——所以结果是一个处于 **`ORDER_REFUND_FAILED` 的
退款订单**，在退款查询和 Portal 的退款
列表中可见并附带该原因。链上没有任何资金移动。因为失败记录已经
存在，用修正后的地址重试是一次**带新
`refundRequestId` 的全新请求**：重发旧 id 返回的是失败记录，不是新的
尝试。重发前请检查 `remainingRefundAmount`。

请使用**自托管（EOA）钱包地址**。基于合约的钱包，包括
多签钱包，不支持作为退款目标，Portal
的退款抽屉里也写明了同样的规则。

Portal 应用相同的约束：在退款抽屉中，链是原支付链的
只读标签，标注为\*"Refund must use the
same chain as the original payment,"\*，地址字段在您输入时按该
链的格式校验，详情页随后显示所用地址。没有任何
Portal 视图展示链上详情——没有交易哈希、确认数或
网络费用。

## 稳定币订单可以部分退款吗？

不可以。已发布的
[支付方式目录](/docs/zh/essentials/payment-methods)将 `USDC` 和
`USDT` 列为**仅支持全额退款**，退款形态检查会强制执行：低于
全额的退款会被拒绝，全额退款后的第二次退款也会被拒绝。请在 **Service → Payin** 的 `Refundable`
列，或您配置响应中的 `refundAllowed` 确认适用于您自己协议的形态
——四种形态及其编码在
[读懂您的支付方式配置](/docs/zh/support/payment-method-config-and-limits-faq)中说明。

所以请把稳定币退款规划为每笔订单一次全有或全无的操作。如果您的
业务需要退回部分价值，那属于退款 API 之外的
商务安排，而不是部分退款。

## 退款的网络费谁付？

Waffo。商户发起退款的链上成本不会从您的
结算余额中扣除，也不会从购物者收到的金额中扣除——购物者
收到全额退款金额。这与上文的异常情形相反，
那里退回给购物者的金额扣除了发送成本。


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