完整支付流程

本指南构建默认无状态支付路径。你的应用拥有订单记录，网关负责引用和协议协调，链状态与 signed receipt 提供支付证据。

准备条件

• 已部署的 x402 网关，例如 https://pay.example.com。
• 商户控制的 EVM payTo 钱包。
• 对应网络上支持 EIP-3009 的 USDC。
• 能签署 EIP-712 typed data 的付款钱包适配器。
• 保存 API key 和 notify HMAC key 的后端密钥系统。

Shell
1npm install x402-paysdk

1. 证明 payTo 所有权

TypeScript
1import {2  createMerchantChallenge,3  merchantChallengeTypedData,4  registerMerchant5} from 'x402-paysdk/merchant';67const gateway = 'https://pay.example.com';8const payTo = '0x1111111111111111111111111111111111111111';9const webhookUrl = 'https://merchant.example/x402/notify';1011const challenge = await createMerchantChallenge(gateway, {12  payTo,13  network: 'base',14  action: 'merchant.register',15  webhookUrl16});1718const signature = await merchantWallet.signTypedData(19  merchantChallengeTypedData(challenge.message)20);2122const credentials = await registerMerchant(gateway, {23  challengeId: challenge.challengeId,24  payTo,25  network: 'base',26  label: '示例商店',27  webhookUrl,28  signature29});

立即把 apiKey、notifyHmacKey 和 notifyHmacKeyId 存入密钥系统。原始凭据只会在签发或轮换时返回。

2. 创建后端 MerchantClient

TypeScript
1import { MerchantClient } from 'x402-paysdk/merchant';23const merchant = new MerchantClient({4  gateway,5  apiKey: process.env.X402_API_KEY!,6  notifyHmacKey: process.env.X402_NOTIFY_KEY!,7  notifyHmacKeyId: process.env.X402_NOTIFY_KEY_ID!,8  payTo,9  network: 'base'10});

这个客户端只能在后端创建，不能序列化到前端状态，也不能记录它的配置。

3. 创建并保存 PaymentRef

金额使用 USDC 原子单位，六位精度下 24000000 表示 24 USDC。

TypeScript
1import { createPaymentRef } from 'x402-paysdk/merchant';23const ref = await createPaymentRef(merchant, {4  payTo,5  network: 'base',6  asset: 'USDC',7  amount: '24000000',8  invoiceId: 'order_7K9M2',9  label: '订单 7K9M2',10  expiresInSecs: 900,11  notifyUrl: webhookUrl12});1314await orders.savePaymentReference({15  orderId: 'order_7K9M2',16  refId: ref.refId,17  refUrl: ref.refUrl,18  expectedAmount: ref.snapshot.amount,19  expectedPayTo: ref.snapshot.payTo,20  expiresAt: ref.snapshot.expiresAt21});

只把 refUrl 和显示信息交给付款端。它可以通过链接、二维码、deep link 或 API payload 传递。

4. 接入付款钱包

TypeScript
1import type { WalletSigner } from 'x402-paysdk/pay';23const wallet: WalletSigner = {4  address: account.address,5  signTypedData: (typedData) => walletClient.signTypedData(typedData)6};

签名前可以先显示并确认精确上下文：

TypeScript
1import { getPaymentRequired } from 'x402-paysdk/pay';23const required = await getPaymentRequired(ref.refUrl);4const offer = required.accepts[0];56renderConfirmation({7  payTo: offer.payTo,8  amount: offer.amount,9  network: offer.network,10  asset: offer.asset11});

5. 授权并结算

TypeScript
1import { pay } from 'x402-paysdk/pay';23const settlement = await pay({4  refUrl: ref.refUrl,5  paymentId: crypto.randomUUID(),6  wallet7});

pay() 会解析 receive URL、获取 402、验证 signed offer 和网关 DID、生成 EIP-3009 typed data、请求钱包签名并提交 PAYMENT-SIGNATURE。

6. 把证据交给后端

TypeScript
1await fetch('/api/orders/order_7K9M2/payment', {2  method: 'POST',3  headers: { 'content-type': 'application/json' },4  body: JSON.stringify({5    txHash: settlement.txHash,6    signedReceipt: settlement.signedPaymentReceipt,7    receipt: settlement.receipt8  })9});

7. 验证收据与链上终局性

TypeScript
1import { verifyReceipt } from 'x402-paysdk/merchant';23const verification = await verifyReceipt(merchant, {4  signedReceipt,5  receipt,6  expectedPayTo: order.expectedPayTo,7  expectedAmount: order.expectedAmount,8  minConfirmations: 39});1011if (!verification.valid || !verification.confirmed) {12  throw new Error(verification.reason ?? '支付尚未达到终局状态');13}1415await orders.markPaidOnce(order.id, {16  txHash: verification.txHash!,17  payer: verification.payer!,18  receipt19});

markPaidOnce 必须是商户数据库内的原子操作。默认网关不会替商户持有履约状态。

8. 把 notify 作为快速提示

TypeScript
1import { verifySettlementNotify } from 'x402-paysdk/merchant';23const result = await verifySettlementNotify(4  request.headers,5  rawBody,6  { [process.env.X402_NOTIFY_KEY_ID!]: process.env.X402_NOTIFY_KEY! },7  sharedNonceStore8);910if (!result.ok) return new Response('invalid notify', { status: 401 });1112await paymentQueue.enqueue(result.notify);13return new Response(null, { status: 204 });

多实例生产环境必须使用共享原子 nonce store。Notify 只能提前唤醒验证流程，不能代替链上终局性。

完成标准

• 付款方在签名前看到准确的 payTo、金额、网络和资产。
• Signed offer 通过固定 signer 或同源 DID 发现建立信任。
• 后端把收据与订单保存的预期上下文逐项匹配。
• 链上转账达到配置的确认数。
• 履约使用一次原子状态转换。
• 凭据、付款签名和原始 notify body 没有进入日志。

继续阅读生产运营来设置恢复和对账。