x402 稳定币收单

x402 是基于 HTTP 402 状态码的开放支付协议：服务端对未付费的请求返回 402 challenge，付款方（通常是 AI Agent）用链上稳定币授权签名重试请求，完成支付后获得资源。Waffo 把 x402 封装为标准收单能力——订单、Webhook、对账与你现有的 Waffo 集成完全一致，链上校验与结算由 Waffo 完成。本页面向两类读者：商户开发者（选择集成模式、调用 Waffo API、判定资源放行）为主；AI Agent 开发者可重点阅读 402 challenge 结构与 PAYMENT-SIGNATURE 提交方式，Agent 侧交互不需要商户 API Key。

两种集成模式

模式一：商户自持 402

你的服务端自己充当 x402 server：向 Agent 返回 402 challenge、接收签名，再通过 order/create 把签名转交 Waffo 结算。适合希望 Agent 全程停留在自己 API 上、愿意实现 x402 协议细节的商户。

模式二：Waffo 托管 402

你只创建订单，把 Waffo 返回的托管地址交给 Agent；402 challenge、签名接收与结算全部由 Waffo 收银台完成。适合不想实现 x402 协议细节、快速上线的商户。

两种模式共用同一个 order/create 接口，区分方式只有一个：请求的 x402Info 里带不带 paymentSignatureHeader——带签名走模式一，不带走模式二。

前提条件

x402 收单需要先通过 Waffo 对接团队完成两项开通：

商户合同开通 CRYPTO / USDC 支付产品
Waffo 侧配置你的链上收款参数

未完成配置时，wallet/inquiry 与 order/create 返回错误码 A0010（商户合同不允许此操作）。

当前支持范围

以下是当前版本的硬性边界，请按此开发，不要预设其他能力：

币种：仅 USDC；orderCurrency 必须为 USDC（同币种收付，不涉及换汇）
网络：仅 Base（生产为 eip155:8453；沙箱为 Base Sepolia eip155:84532）
scheme：仅 exact（按 challenge 中的金额精确结算）
授权次数：EIP-3009 授权在链上单次消费——一个签名只能结算一次，不支持「一次授权、多次扣款」
幂等：paymentRequestId 必填；同一单重复 order/create 会返回已有订单的真实状态，不会重复结算（参见幂等机制）

获取链上收款参数

模式一构造 402 challenge 前，先调用 POST /api/v1/wallet/inquiry 获取收款参数。该接口只做查询：不创建订单、不校验金额。

curl -X POST https://api-sandbox.waffo.com/api/v1/wallet/inquiry \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-SIGNATURE: YOUR_RSA_SIGNATURE" \
  -d '{
    "paymentRequestId": "x402-order-10001",
    "merchantInfo": { "merchantId": "M000001" },
    "orderCurrency": "USDC"
  }'

{
  "code": "0",
  "msg": "Success",
  "data": {
    "network": "eip155:84532",
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "payTo": "0xc15Ea3D0b7A29c41F8b26aD5c30F49E20e510e71"
  }
}

字段	说明
`network`	CAIP-2 网络标识。沙箱返回 Base Sepolia `eip155:84532`，生产返回 Base 主网 `eip155:8453`
`asset`	USDC 代币合约地址（随环境与网络变化，生产 Base 主网为 `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`）
`payTo`	Waffo 平台收款地址。Waffo 链上收款后按合同结算给你

三个字段都来自 Waffo 配置，请原样用于构造 challenge：payTo 不能替换为你自己的钱包地址，Agent 签名中的收款地址与金额会在结算前被链上校验。

模式一：商户自持 402

你需要做四件事：

调 wallet/inquiry 取 network / asset / payTo，按定价构造 402 challenge（金额用原子单位，scheme 固定 exact）返回给 Agent
从 Agent 的重试请求头 PAYMENT-SIGNATURE 中取出签名，原样放入 order/create 的 x402Info.paymentSignatureHeader（不要解码后重新组装）
按同步响应的 orderStatus 决定放行：PAY_SUCCESS 放行，PAY_IN_PROGRESS 等 Webhook 或 order/inquiry 终态，ORDER_CLOSE 拒绝
放行时把响应中的 x402Info.x402Response 作为 PAYMENT-RESPONSE 头返回给 Agent，作为符合 x402 协议的结算回执

curl -X POST https://api-sandbox.waffo.com/api/v1/order/create \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-SIGNATURE: YOUR_RSA_SIGNATURE" \
  -d '{
    "paymentRequestId": "x402-order-10001",
    "merchantOrderId": "x402-order-10001",
    "orderCurrency": "USDC",
    "orderAmount": "9.99",
    "orderDescription": "API usage credits",
    "notifyUrl": "https://merchant.example.com/webhook/waffo",
    "merchantInfo": { "merchantId": "M000001" },
    "userInfo": { "userId": "agent_7f3e", "userTerminal": "WEB" },
    "paymentInfo": { "productName": "ONE_TIME_PAYMENT", "payMethodName": "USDC" },
    "x402Info": {
      "x402Request": true,
      "paymentSignatureHeader": "eyJ4NDAyVmVyc2lvbiI6Miwic2NoZW1lIjoiZXhhY3QiLC4uLn0="
    }
  }'

{
  "code": "0",
  "msg": "Success",
  "data": {
    "paymentRequestId": "x402-order-10001",
    "merchantOrderId": "x402-order-10001",
    "acquiringOrderId": "A202607060001",
    "orderStatus": "PAY_SUCCESS",
    "x402Info": {
      "x402Request": true,
      "paymentSignatureHeader": "eyJ4NDAyVmVyc2lvbiI6Miwic2NoZW1lIjoiZXhhY3QiLC4uLn0=",
      "x402Response": "eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4Li4uIn0="
    }
  }
}

其余必填字段（goodsInfo、orderRequestedAt 等）与普通一次性支付建单一致，以 API Reference 为准。 paymentSignatureHeader 是 base64 编码的 x402 PaymentPayload，解码后结构如下（由 Agent 侧 x402 SDK 生成，商户无需构造）：

{
  "x402Version": 2,
  "scheme": "exact",
  "network": "eip155:84532",
  "payload": {
    "signature": "0x<65 字节 EIP-712 签名>",
    "authorization": {
      "from": "0x<Agent 钱包地址>",
      "to": "0xc15Ea3D0b7A29c41F8b26aD5c30F49E20e510e71",
      "value": "9990000",
      "validAfter": "0",
      "validBefore": "1783340000",
      "nonce": "0x<32 字节随机数（防重放，非递增）>"
    }
  }
}

签名中 authorization.to 必须等于 wallet/inquiry 返回的 payTo，authorization.value 必须等于 orderAmount 的原子单位表示（换算规则见下文「金额与小数位」）。任一不一致都会在结算前校验失败，订单进入 ORDER_CLOSE。因此你在 402 challenge 中给 Agent 的定价必须与 order/create 的 orderAmount 一致。

x402Response 是 base64 编码的结算回执（x402 SettlementResponse），仅在 orderStatus = PAY_SUCCESS 时返回，解码后：

{
  "success": true,
  "transaction": "0x8f4e2b7c9d1a4f6e8b3c5d7a9e1f2b4c6d8e0a2c4e6f8a0b2c4d6e8f0a1b3c5d",
  "network": "eip155:84532",
  "payer": "0x51E2aF03D0A5c3C7dF83Db9F4b0a2E51D8c19aC3"
}

transaction 是链上交易 hash，可用于对账与链上核验；payer 是 Agent 的付款钱包地址。

模式二：Waffo 托管 402

你需要做三件事：

order/create 传 x402Info: { "x402Request": true }（不带签名），并带上 successRedirectUrl / failedRedirectUrl
解析响应中的 orderAction（JSON 字符串）取出 webUrl，将 Agent 302 重定向过去；之后的 402 challenge、签名接收、结算全部发生在 Waffo 收银台
以 Webhook 或 order/inquiry 返回的 orderStatus 为准放行资源

curl -X POST https://api-sandbox.waffo.com/api/v1/order/create \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-SIGNATURE: YOUR_RSA_SIGNATURE" \
  -d '{
    "paymentRequestId": "x402-order-10002",
    "merchantOrderId": "x402-order-10002",
    "orderCurrency": "USDC",
    "orderAmount": "9.99",
    "orderDescription": "API usage credits",
    "notifyUrl": "https://merchant.example.com/webhook/waffo",
    "successRedirectUrl": "https://merchant.example.com/x402/return",
    "failedRedirectUrl": "https://merchant.example.com/x402/failed",
    "merchantInfo": { "merchantId": "M000001" },
    "userInfo": { "userId": "agent_7f3e", "userTerminal": "WEB" },
    "paymentInfo": { "productName": "ONE_TIME_PAYMENT", "payMethodName": "USDC" },
    "x402Info": { "x402Request": true }
  }'

{
  "code": "0",
  "msg": "Success",
  "data": {
    "paymentRequestId": "x402-order-10002",
    "merchantOrderId": "x402-order-10002",
    "acquiringOrderId": "A202607060002",
    "orderStatus": "AUTHORIZATION_REQUIRED",
    "orderAction": "{\"actionType\":\"WEB\",\"webUrl\":\"https://cashier.waffo.com/cashier/api/v1/x402/7sKq9WfR2mXt\"}"
  }
}

Agent 访问 webUrl 收到 HTTP 402，challenge 在响应体中（x402 协议规定 challenge 位于 body，没有专门的响应头）：

{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "maxAmountRequired": "9990000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0xc15Ea3D0b7A29c41F8b26aD5c30F49E20e510e71",
      "maxTimeoutSeconds": 600,
      "extra": { "name": "USDC", "version": "2" }
    }
  ]
}

Agent 签名后，用与首次访问相同的 HTTP 方法重试同一 URL，把签名放在 PAYMENT-SIGNATURE 请求头（对应 x402 规范中的 X-PAYMENT），无需任何商户凭证：

curl "https://cashier.waffo.com/cashier/api/v1/x402/7sKq9WfR2mXt" \
  -H "PAYMENT-SIGNATURE: eyJ4NDAyVmVyc2lvbiI6Miwic2NoZW1lIjoiZXhhY3QiLC4uLn0="

结算完成后收银台以 302 将 Agent 带回你的 successRedirectUrl 或 failedRedirectUrl。该托管地址同时兼容浏览器访问（渲染收银台页面）与 x402 client 访问（返回协议响应）。

302 回跳只用于流程衔接，不是支付凭证。判定「已支付」只能依据 Webhook 通知或 order/inquiry 查询到的 orderStatus = PAY_SUCCESS——回跳可能伪造、可能丢失，且回跳时结算可能尚未落定。

支付成功后，Webhook 通知与 order/inquiry 响应会附带 x402Info.x402Response（字段结构与模式一相同），其余通知结构与普通订单一致，参见 Webhook 事件类型。

模式对比

维度	模式一：商户自持 402	模式二：Waffo 托管 402
谁充当 x402 server（发 402、收签名）	商户服务端	Waffo 收银台
是否需要实现 x402 协议细节	是（构造 challenge、解析签名头）	否
`order/create` 是否带签名	带（`x402Info.paymentSignatureHeader`）	不带
建单响应	直接返回终态或 `PAY_IN_PROGRESS`	`AUTHORIZATION_REQUIRED` + 托管地址
跳转	无（Agent 全程请求商户 API）	商户 302 → 收银台 302 回跳
资源放行依据	同步响应 / Webhook / inquiry 的 `orderStatus`	Webhook / inquiry 的 `orderStatus`
适合	自建 x402 服务、深度定制的商户	快速上线、不碰协议细节的商户

订单状态语义（PAY_IN_PROGRESS、AUTHORIZATION_REQUIRED 等）与其他支付方式一致，参见支付生命周期。

金额与小数位（两层单位）

同一笔交易中的金额有两层表示，不要混用：

层	字段	表示方式	示例（9.99 USDC）
Waffo API 层	`orderAmount`	String，最多 2 位小数	`"9.99"`
链上 / x402 协议层	`value`、`maxAmountRequired`	String，原子单位整数（USDC 链上精度 6 位）	`"9990000"`

换算规则：原子单位 = 金额 × 10⁶。币种与金额中 USDC 的 2 位小数指 Waffo API 层的 orderAmount；402 challenge 与 EIP-3009 签名中的金额始终是原子单位。模式一中两层金额必须对应同一数值，否则结算校验失败。

错误码

x402 复用 Waffo 既有对外错误码，msg 会说明具体原因：

错误码	含义	x402 场景下的常见触发
`A0003`	参数校验失败	challenge / 签名的 scheme 不是 `exact`；缺少 `paymentRequestId`
`A0007`	不支持的交易币种	`orderCurrency` 不是 `USDC`，或商户没有可用的同币种 USDC 合同
`A0010`	商户合同不允许此操作	未开通 CRYPTO/USDC 支付产品，或链上收款参数未配置

完整错误码列表见错误码参考。

常见问题

沙箱环境用的是哪条链？

沙箱走 Base Sepolia 测试网（eip155:84532），USDC 合约地址为 0x036CbD53842c5426634e7929541eC2318f3dCF7e；生产走 Base 主网（eip155:8453），USDC 合约地址为 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913。两个环境的 network / asset / payTo 都以 wallet/inquiry 实际返回为准。

支持其他币种或其他网络吗？

当前仅支持 USDC + Base 网络，orderCurrency 传其他币种会返回 A0007。

一次授权可以多次扣款吗？

不可以。x402 的 exact scheme 基于 EIP-3009 transferWithAuthorization，其 nonce 在 USDC 合约侧单次消费：签名一旦结算即作废，再次提交会在链上直接失败。订阅式、按量多次扣款不属于 x402 能力范围。

orderStatus 是 PAY_IN_PROGRESS，可以先放行资源吗？

不可以。PAY_IN_PROGRESS 只表示链上处理中，最终可能成功也可能失败。只有 orderStatus = PAY_SUCCESS 才能放行资源，终态通过 Webhook 或 order/inquiry 收敛。

402 challenge 在响应头还是响应体里？

在响应体（JSON body）里，没有携带 challenge 的响应头。x402 交互中唯一的协议请求头是 Agent 提交签名用的 PAYMENT-SIGNATURE（对应 x402 规范的 X-PAYMENT）；结算回执通过 x402Info.x402Response 字段返回，对应规范的 X-PAYMENT-RESPONSE。

这和「AI 集成工具（waffo-integrate）」是一回事吗？

不是。AI 集成工具是用 AI 编码工具帮你生成 Waffo SDK 集成代码；本页是 AI Agent 作为付款方用稳定币购买你的服务。两者可以同时使用，但解决的问题不同。

快速开始

核心概念

集成

Webhook

SDK

工具与参考

两种集成模式

模式一：商户自持 402

模式二：Waffo 托管 402

前提条件

当前支持范围

获取链上收款参数

模式一：商户自持 402

模式二：Waffo 托管 402

模式对比

金额与小数位（两层单位）

错误码

常见问题

延伸阅读

​两种集成模式

模式一：商户自持 402

模式二：Waffo 托管 402

​前提条件

​当前支持范围

​获取链上收款参数

​模式一：商户自持 402

​模式二：Waffo 托管 402

​模式对比

​金额与小数位（两层单位）

​错误码

​常见问题

​延伸阅读

两种集成模式

前提条件

当前支持范围

获取链上收款参数

模式一：商户自持 402

模式二：Waffo 托管 402

模式对比

金额与小数位（两层单位）

错误码

常见问题

延伸阅读