Skip to main content
稳定币支付未按预期到账时会发生什么,以及当您退款一笔 USDC 或 USDT 订单时 必须发送什么。订单字段、链的选择 和确认行为见稳定币支付; 所有支付方式通用的规则见退款 FAQ。

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

Waffo 会把不符合规范的转账归入以下情形之一——您提交工单时,支持团队使用的就是这些标签。 表格贯穿两条规则:结算始终基于订单 金额,绝不基于实际转账金额;向购物者退回资金 不是您账户上的退款——没有退款订单,也不会出现在您的退款报表里。

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

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

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

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

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

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

购物者从交易所付款时,为什么退回很慢?

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

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

Portal 里任何地方都看不到,这是实话而不是缺了一个 页面:没有任何面向商户的视图携带链上详情。交易列表和 交易详情没有链的列、没有交易哈希、没有确认 数,也没有收到金额与订单金额的对比,因此多付、 少付或错链转账不是您能查到的内容。 您能看到的是订单:它要么到达了最终成功状态,要么 没有。上述一切说的是资金去了哪里,而不是 订单,并且这些情形都不会在您账户上创建退款订单——所以 它们也永远不会出现在您的退款列表或退款报表中。 于是当购物者坚称已付款时只剩一条路:把订单 id 连同 购物者能提供的交易哈希、链和代币一起提交给 支持团队。这四项事实就是识别该情形的依据。 唯一的例外是 x402 签名路径,成功的订单会在 API 上返回 链上结算回执,包含交易哈希——见 x402 稳定币收单。

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

每笔 USDC 和 USDT 退款都必须填写退款目标地址。请把地址放在 /api/v1/order/refund 的 extendInfo 里。外层 extendInfo 的值是一个 包含 JSON 的字符串,不是嵌套的 JSON 对象。 下面是完整的请求体示例。请把每个占位值替换为订单和购物者的实际值:
refundAmount 必须填写订单的全部可退金额。退款地址必须适用于原支付 使用的链。省略地址时,请求会在前置参数校验时失败——A0003,错误信息为 Parameter validation failed ( missing refund optional field )。 msgParams.missingFields 中会包含 extendInfo.refundAddress。此时不会创建 退款订单,之后也没有可查询的内容;对法币订单它是不必要的,传了会被忽略。 请把这当作一次集成变更: 如果您已经在调用退款 API,之后又接入稳定币,请先更新您的 退款路径。请自行向购物者收集地址——Waffo 无法 联系您的购物者索要。

我能退到另一条链,或者任意钱包吗?

两者都不行。链从原支付读取并锁定;退款请求上没有 链参数,任何试图传入的都会被忽略。 链决定接受哪种地址格式,退款处理时会按 该链的格式校验地址: 两个格式细节值得写进您自己的输入校验,因为它们 确实会被检查,而且常常让人意外:
  • **大小写混合的 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 视图展示链上详情——没有交易哈希、确认数或 网络费用。

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

不可以。已发布的 支付方式目录将 USDC 和 USDT 列为仅支持全额退款,退款形态检查会强制执行:低于 全额的退款会被拒绝,全额退款后的第二次退款也会被拒绝。请在 Service → Payin 的 Refundable 列,或您配置响应中的 refundAllowed 确认适用于您自己协议的形态 ——四种形态及其编码在 读懂您的支付方式配置中说明。 所以请把稳定币退款规划为每笔订单一次全有或全无的操作。如果您的 业务需要退回部分价值,那属于退款 API 之外的 商务安排,而不是部分退款。

退款的网络费谁付?

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