跳到正文

商户 SDK

注册商户、管理引用和订单、验证通知、发起退款并完成链上对账。

x402-paysdk/merchant 只能放在后端。它处理商户 API key、notify HMAC key、钱包所有权证明、订单、退款、收据和对账。

使用 payTo 证明注册

  1. 使用目标 payTo、网络和 webhook URL 调用 createMerchantChallenge()。
  2. 用控制该地址的商户钱包签署返回的 message 或 typed data。
  3. 携带 challenge id 和签名调用 registerMerchant()。
  4. 把返回的 API key 和 notify HMAC key 存入 secrets manager；原始密钥只返回一次。

创建客户端

TypeScript
import { MerchantClient, getMerchantProfile } from 'x402-paysdk/merchant';const merchant = new MerchantClient({  gateway: 'https://gateway.example',  apiKey: process.env.X402_API_KEY!,  notifyHmacKey: process.env.X402_NOTIFY_KEY,  notifyHmacKeyId: process.env.X402_NOTIFY_KEY_ID,  payTo: process.env.X402_PAY_TO,  network: 'eip155:8453'});const profile = await getMerchantProfile(merchant);

履约规则

把 notify 当作低延迟提示。进行不可逆履约前，要验证 signed receipt 和所需链上确认数。由于 webhook 可能延迟或丢失，应定期运行 reconcile()。

订单模式是可选能力。启用后必须使用随机 refund intent 和网关订单 API，不能根据未绑定的 orderId 或 refundId 查询参数授权退款。