> ## 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：两条集成路径选哪一条、要发送的确切链值、每条路径中收款地址如何工作、金额和小数规则、支付窗口、购物者完成转账意味着什么和不意味着什么、法币结算，以及稳定币订单在 Portal 中的位置。

本页涵盖通过常规钱包 / 托管收银台路径接受稳定币。
基于 x402 协议构建的 AI Agent 路径有自己的范围、请求
字段和错误行为，记载在
[x402 稳定币收单](/docs/zh/developer-docs/use-cases/x402-stablecoin-acquiring)。
异常情形和退款在
[稳定币异常与退款](/docs/zh/support/stablecoin-exceptions-faq)。

接受稳定币按商户合同开通——在构建之前，请让集成团队
为你开通 CRYPTO 支付产品和你的链集合。

## 接受稳定币有几种方式，我该选哪种？

两种，而且它们不是同一个集成的变体——它们在付款方是谁
以及你的服务器做什么上都不同：

| | 钱包 / 托管收银台路径 | x402 签名路径 |
| - | - | - |
| 付款方是 | 持有加密钱包的人 | 通常是 AI Agent |
| 记载于 | 本页 | [x402 稳定币收单](/docs/zh/developer-docs/use-cases/x402-stablecoin-acquiring) |
| 币种 | `USDC` 和 `USDT` | 仅 `USDC` |
| 链 | 你签约的链集合 | 仅 Base |
| 付款方如何支付 | 转账到收款地址 | 签署链上授权 |
| 收款地址 | 按订单发放 | 由 `wallet/inquiry` 返回的商户级地址 |
| 支付窗口 | 订单的过期时间 | 402 challenge 中的超时 |
| 退款 | `order/refund` 上的 `refundAddress` | 相同 |

按付款方而不是按偏好选择：持有钱包的人无法支付 x402
challenge，而 Agent 没有浏览器来渲染收银台。如果你两类都卖，
就两条都集成。

## 我在创建订单时要发送什么来接受稳定币？

在钱包路径上，三样东西标识一个稳定币订单：

| 字段 | 值 |
| - | - |
| `payMethodType` | `CRYPTO` |
| `payMethodName` | `USDC` 或 `USDT` |
| `payMethodProperties.cryptoChain` | 购物者将支付的链——[取值见下文](#what-exactly-do-i-put-in-the-chain-field) |

该方式在目录中登记在全球地区代码 `GLB` 下而不是某个
国家，所以它不按购物者所在国家筛选。定价与任何
其他跨币种订单一样：把 `orderCurrency` 和 `orderAmount` 保持为你的
定价币种（通常是 `USD`），并把 `userCurrency` 设为 `USDC` 或 `USDT`——
购物者实际支付的币种。参见
[定价币种策略](/docs/zh/developer-docs/use-cases/pricing-currency)。

## 我必须自己让购物者选链吗？

只有当你运行自己的收银台页面时。

* **Waffo 托管收银台**——省略 `payMethodProperties.cryptoChain`。
  咨询步骤会把它作为缺失字段连同该订单可用的链
  选项一起返回，收银台会在订单最终确定之前收集购物者的选择。
* **你自己的收银台页面**——自己呈现链选择，并在
  `payMethodProperties.cryptoChain` 中回传所选的值。

把返回的选项列表视为权威：它反映的是你的账户和该稳定币
可用的内容，可能比下面的
平台级列表更窄。

## 我能只提供一条链，让购物者不会选错吗？

可以——这正是选项列表的用途。为订单提供的链
来自你账户的配置，所以单链配置会产生
单链选项列表，在托管收银台上也就没有什么值得一提的链选择器。
请向你的集成联系人索取你想要的链集合，而不是
在客户端过滤列表：客户端过滤仍然会让更宽的集合
在 `order/create` 上可被接受。

注意这**不能**防止什么。收窄链只是移除了购物者支付
*哪个订单*的选择；它无法阻止他们从钱包在其他
链上发送资金，那就是
[稳定币异常与退款](/docs/zh/support/stablecoin-exceptions-faq)中的 `WRONG_CHAIN` 情形。

## 链字段里到底要填什么？

链的**代码**，作为字符串——`BASE`，不是 `Base`，也不是数字链
ID。匹配不区分大小写，每条链的简称也可以
作为代码的替代被接受，但请发送代码：它是订单上
返回的值，也是退款路径读取的值。

| 链 | 要发送的代码 | 同样接受的简称 | 地址族 |
| - | - | - | - |
| Ethereum | `ETHEREUM` | `ETH` | EVM |
| Polygon | `POLYGON` | `MATIC` | EVM |
| Arbitrum One | `ARBITRUM` | `ARB` | EVM |
| Base | `BASE` | `BASE` | EVM |
| Optimism | `OPTIMISM` | `OP` | EVM |
| Avalanche | `AVALANCHE` | `AVAX` | EVM |
| BNB Smart Chain | `BSC` | `BSC` | EVM |
| Solana | `SOLANA` | `SOL` | Solana |
| Tron | `TRON` | `TRX` | Tron |

测试网是单独的代码，在你的沙箱为其配置的情况下可用：

| 测试网 | 代码 | 对应主网 |
| - | - | - |
| Ethereum Sepolia | `ETH-SEPOLIA` | `ETHEREUM` |
| Polygon Amoy | `AMOY` | `POLYGON` |
| Arbitrum Sepolia | `ARBITRUM_SEPOLIA` | `ARBITRUM` |
| Base Sepolia | `BASE_SEPOLIA` | `BASE` |
| Optimism Sepolia | `OPTIMISM_SEPOLIA` | `OPTIMISM` |
| Avalanche Fuji | `FUJI` | `AVALANCHE` |
| Solana Testnet | `SOLANA_TEST` | `SOLANA` |

Tron 和 BNB Smart Chain 没有测试网代码，所以这两条链无法
在测试网上演练。

两个经常出现的命名问题：

* **`BSC` 是 BNB Smart Chain。** 该链的代码是 `BSC`，其网络是 BNB
  Smart Chain；单独的"BNB"是该网络的代币，不是链代码。请发送
  `BSC`。
* **Avalanche 指的是 C-Chain。** 只有 C-Chain（EVM）地址有效；
  X-Chain 和 P-Chain 地址会被直接拒绝，包括在退款时。

**地址族**这一列是你要据以构建的：它决定了链接受的
地址格式，这在退款时最为重要——参见
[稳定币异常与退款](/docs/zh/support/stablecoin-exceptions-faq)。

## 链字段是必填的吗？我不填会怎样？

在请求上不是必填的，但没有链订单就无法支付，
所以不填会有两种结果之一，绝不会有默认值：

* 在**托管收银台**上，咨询步骤把它作为缺失字段连同
  可用选项一起报告，由购物者的选择提供它。
* 在**你自己的收银台**上，你会得到同样的缺失字段响应，
  收集选择并重新发送是你的工作。

没有兜底链。不要假设会为你选择最便宜或最流行的链。

## 支持哪些稳定币？

钱包路径上是 `USDC` 和 `USDT`；x402 路径上仅 `USDC`。没有其他
代币——没有非稳定币代币，没有小市值代币，也没有商户自发行的
代币。

发送到收款地址的任何其他东西都不是有效支付：转账
链的原生代币（例如 ETH）或任何其他代币都不能支付
订单，在订单所属链以外的链上转账也不能。

## 有最小或最大金额吗？

有，而且它像其他任何支付方式一样在你的协议上，不是特殊的
稳定币规则。已发布的
[支付方式目录](/docs/zh/essentials/payment-methods)载有
`USDC` 和 `USDT` 的目录级范围；实际适用于
你的范围是你自己该方式配置条目上的 `orderAmountMin` / `orderAmountMax`，
可从 `/api/v1/paymethodconfig/inquiry` 或 Portal 中的 **Service →
Payin** 读取。

在创建订单之前先检查它。超出范围的金额会在
订单创建时以 `A0008` 被拒绝——参见
[限额、币种与配置错误](/docs/zh/support/error-codes-and-limits-supplement)
了解它与两个账户级限额的区别。

## 稳定币金额用几位小数？

两位，在每个 Waffo API 字段上，与两位小数的法币完全一样——参见
[币种与金额](/docs/zh/developer-docs/core-concepts/currency)。链上
这些代币使用 6 位小数的原子单位；Waffo 处理该转换，所以你的
请求和报表都不携带原子单位，而区块浏览器显示的
金额单位与你发送的不同。

因此代币的链上精度**不会**改变你发送的内容：
同一个 `orderAmount` 字符串在每条链上都是正确的，你永远不用自己
缩放它。唯一需要你自己构造原子单位的地方是 x402
签名路径，那里的 challenge 和签名都是原子单位——
那个页面详细说明了转换。

## 收款地址是我的、按订单的，还是固定的？

取决于路径，而且两个答案确实不同：

| 路径 | 地址 | 我能缓存它吗？ |
| - | - | - |
| 钱包 / 托管收银台 | **按订单**发放 | **不能** |
| x402 签名路径 | 由 `wallet/inquiry` 返回的**商户级**收款地址 | 不能——每个订单都获取一次并原样使用 |

在钱包路径上，地址绑定到一个订单，并在该订单
结束时释放，这意味着它之后可能被发放给**另一个**订单。这
就是为什么这条规则是绝对的而不是偏好：转账到
你缓存的地址不会支付你为之缓存的订单，而一旦地址
已经转给了别的订单，它就根本无法归属到原订单。

两条路径都不会给你一个属于你自己、可以公布、打印在发票上或
硬编码的地址。在两条路径中，地址都是 Waffo 的；Waffo 在链上收款，
并按你的合同向你结算。

## 购物者付到了一个被回收的地址，会怎样？

没有好结果，这值得在设计上防范而不是事后处理。一旦
订单的地址被释放，迟到的转账会落入
[稳定币异常与退款](/docs/zh/support/stablecoin-exceptions-faq)中的某个
未匹配情形：它不会
支付原订单，也不会支付当前持有该地址的订单，
因为金额和订单对不上。

实用的防护：绝不要在该订单的支付页面之外渲染稳定币地址，
绝不要让购物者"复用上次的地址"，绝不要
显示已过期订单的二维码。

## 支付二维码带金额吗？

不要假设它带。给购物者可靠的指示是：**在窗口关闭前，
在订单的链上，以订单的代币，发送恰好等于订单金额的款项**
——四项全部，来自支付页面。预填金额的钱包
是一种便利，不是保证，购物者修改过的金额会产生
多付或少付情形，而不是已支付的订单。

## 购物者有多长时间支付？

订单的过期时间，与其他所有支付方式是同一机制：
除非你在 `order/create` 上发送 `orderExpiredAt`，否则为合同默认值。参见
[支付超时与终态](/docs/zh/support/payment-timeout-and-finality-faq)。

两件稳定币特有的需要规划的事：

* 窗口必须覆盖**购物者的操作加上链的确认
  时间**，而不仅仅是购物者的操作。对钱包重定向来说宽裕的窗口
  在确认慢的链上可能很紧。
* 窗口关闭后到达的转账不会支付订单。它
  成为 `LATE_PAID` 情形，之后没有办法把它附加到已关闭的
  订单上。

## 购物者的钱包说转账成功了——为什么订单还在处理中？

因为只有当转账在链上满足确认要求后，订单才会推进到成功，
而这个等待是链的属性，不是
Waffo 的。钱包显示"已发送"与支付成为
终态不是同一个事件。等待多长时间在不同链之间差异很大：

* 具有近即时确定性终态的链（例如 Avalanche、
  Polygon）确认最快。
* Ethereum 主网等待区块确认深度，所以明显
  更慢。
* 乐观 Rollup L2（Arbitrum、Base、Optimism）最慢：排序器
  在几秒内接受转账，但确认要等待该批次在 Ethereum 上
  被确认。

所以请向购物者显示"等待网络确认"状态，并把
支付结果Webhook 通知或订单查询视为成功的唯一事实来源
——绝不是钱包自己的确认页面，也绝不是你自己查看的区块浏览器。

## 订单处理了一段时间了。它还在等待，还是已经失败了？

读订单，不要读链。处于非终态的订单仍在进行中；
状态机与其他所有支付方式相同，所以关于哪些状态是终态、哪些不是
的规则同样适用——参见
[支付生命周期](/docs/zh/developer-docs/core-concepts/payment-lifecycle)和
[支付超时与终态](/docs/zh/support/payment-timeout-and-finality-faq)。

你不能做的是从链慢推断失败，或从在区块浏览器上找到了
转账推断成功。如果订单到过期时仍未到达
终态，它会关闭；如果资金以不符合规格的方式到达，它会成为
某种异常情形，支持人员可以凭订单 ID 和
交易哈希看到。

## 我收到的是稳定币还是法币？

法币。购物者支付的 USDC 或 USDT 在支付成功时通过
`USD/USDC` 和 `USD/USDT` 币种对转换，下游的一切——你的
未结算余额、结算批次和报表、以及提现——都保持
你的结算币种。你永远不持有稳定币，所以你不承担代币
价格风险，也不承担链上手续费风险。

因为转换发生在**支付成功时**而不是订单创建时，
汇率是那一刻的汇率。稳定币订单使用与其他任何跨币种订单
相同的跨币种机制，所以汇率机制以及能否
锁定报价，在
[汇率](/docs/zh/support/exchange-rates-faq)和
[定价币种策略](/docs/zh/developer-docs/use-cases/pricing-currency)中说明，
而不是在这里特殊处理。

## 稳定币订单在 Portal 中显示在哪里？

在普通的交易列表中，像其他任何东西一样筛选。两个筛选项
就能找到：

| 筛选项 | 值 |
| - | - |
| Payment method type | `CRYPTO` |
| Payment method | `USDC` 或 `USDT` |

Portal **不**提供的是任何链上细节：交易列表或交易详情上
没有链列、没有链筛选、没有交易哈希、没有确认数，也没有
网络手续费数字。链出现的唯一地方是退款抽屉，
在那里它以只读方式显示为原支付使用的链。

所以如果你的对账需要每个订单的链或交易哈希，
不要计划从 Portal 导出中获取。在 x402 路径上，哈希可以
从 API 获得——成功时返回的结算回执携带它，那个页面
记载了它的形态。在钱包路径上，请带订单 ID 向支持提出。

## 要开通稳定币我需要什么？

两个开通步骤，都通过你的集成联系人安排：你合同上的 CRYPTO
支付产品，以及你的链集合。在两者都就位之前，
稳定币订单创建会以合同不允许被拒绝（`A0010`）。

开通本身遵循常规路径，包括在哪里查看其状态——
参见[支付方式开通](/docs/zh/support/payment-enrollment-faq)。之后添加
链与添加支付方式是同类请求：它是
Waffo 侧的配置变更，不是你能自己开启的东西。

## 接下来我该看哪里？

* [稳定币异常与退款](/docs/zh/support/stablecoin-exceptions-faq)——
  多付、少付、迟到、错链、错代币，以及退款必须携带什么
* [x402 稳定币收单](/docs/zh/developer-docs/use-cases/x402-stablecoin-acquiring)——
  端到端的 AI Agent 路径
* [支付超时与终态](/docs/zh/support/payment-timeout-and-finality-faq)——
  订单过期以及哪些状态是终态
* [读懂你的支付方式配置](/docs/zh/support/payment-method-config-and-limits-faq)——
  你自己 `USDC` / `USDT` 的金额范围和可用性
* [结算报表](/docs/zh/support/settlement-reports-faq)——转换后的
  稳定币支付如何出现在结算中


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