商户 API

x402-paysdk/merchant 的认证、refs、订单、退款、收据、notify、交易历史和对账 API。

TypeScript
1import { MerchantClient } from 'x402-paysdk/merchant';

该入口只能运行在后端，负责 bearer credential、notify HMAC key、商户控制的钱包 signer 和业务证据。

MerchantClient

TypeScript
1const client = new MerchantClient({2  gateway: 'https://pay.example.com',3  apiKey: process.env.X402_API_KEY!,4  notifyHmacKey: process.env.X402_NOTIFY_KEY,5  notifyHmacKeyId: process.env.X402_NOTIFY_KEY_ID,6  notifyNonceStore,7  merchantWalletSigner,8  payTo,9  network: 'base'10});

参数	用途
`gateway`	规范网关 origin
`apiKey`	认证请求所需 bearer key
`notifyHmacKey`, `notifyHmacKeyId`	当前 notify credential
`notifyNonceStore`	高层 notify 验证使用的原子 replay store
`merchantWalletSigner`	反向 x402 退款使用的商户 signer
`payTo`, `network`	商户操作和退款的默认值

client.request<T> 只允许同源绝对 path，不能逃离配置的 gateway origin。

商户注册和 key

函数	用途
`createMerchantChallenge`	请求 payTo 所有权挑战
`merchantChallengeSigningMessage`	生成规范 EIP-191 文本
`merchantChallengeTypedData`	生成 EVM EIP-712 typed data
`registerMerchant`	提交签名并获取一次性 credential
`getMerchantProfile`	读取已认证 profile
`rotateMerchantKey`	轮换 `apiKey` 或 `notifyHmacKey`
`revokeOldMerchantKey`	撤销旧的租户 key

注册返回 merchantId、apiKey、notifyHmacKey、notifyHmacKeyId 和 payTo。原始 key 必须立即保存。

Ref 管理

createPaymentRef、getRef、listRefs、revokePaymentRef 和 revokePayTo 使用 MerchantClient 中的 gateway 与 API key。创建参数与 receiver API 相同，但不再重复 credential 字段。

可选 order mode

函数	主要参数
`createOrder`	payTo、amount、asset、network、orderId、description、metadata、expiry
`getOrder`	client、orderId
`listOrders`	status、limit、cursor
`cancelOrder`	client、orderId
`createOrderRefund`	orderId、amount、refundId、originalPaymentRef、expiry
`getRefundStatus`	client、orderId、refundId
`listRefunds`	client、orderId

退款

refund(client, options) 使用商户钱包发起反向 x402。Order mode 会先创建绑定的 refund intent；无状态模式需要 originalPayer、随机 refundId、network、原始 receipt hash、原始金额、累计退款、sequence 和 FULL | PARTIAL 结果。

rejectRefund 用于生成 signed REJECTED receipt，不移动资金，也不会调用 facilitator。

收据与链验证

函数	用途
`verifyReceipt`	验证 payment receipt 和链转账
`verifyRefundReceipt`	验证 refund receipt 和反向转账
`verifySignedPaymentReceipt`	本地验证签名与预期字段
`verifySignedRefundReceipt`	本地验证退款签名与上下文
`paymentReceiptContentHash`	规范 payment receipt ref
`refundReceiptContentHash`	规范 refund receipt ref
`getTxStatus`	有界交易状态
`getPaymentHistory`	有界 Transfer log 历史

本地签名验证证明网关 attestation，网络验证证明链上终局性。

Notify

函数	防重放	用途
`verifySettlementNotify`	是	验证 HMAC、header/body 绑定、schema、timestamp 和 nonce
`verifyNotifySignature`	是	验证 envelope，不解析 event body
`notifyMiddleware`	是	使用 raw body 的 Express-compatible middleware
`createMemoryNotifyNonceStore`	仅单进程	测试与本地开发
`verifyNotifySignatureWithoutReplayProtection`	否	仅诊断，不能保护 side effect

多实例生产系统必须实现共享原子 NotifyNonceStore.putIfAbsent(key, expiresAt)。

对账

reconcile(client, options) 接收 payTo、fromBlock、有界 limit、付款/退款收据、trusted signer、确认数和 verifyChain。返回 incoming/outgoing evidence、anomalies、lastBlock 和可选 cursor，不会自动修改商户订单。

异常包括无收据转账、无转账收据、签名/链验证失败、重复收据、退款证据不匹配、累计退款不一致和超额退款。