收款 API

TypeScript
1import { createPaymentRef } from 'x402-paysdk/receive';

收款入口只管理支付引用，不签署付款、不持有商户订单状态，也不决定履约。

函数

函数	签名	网关路由
createPaymentRef	(options: CreatePaymentRefOptions) => Promise<PaymentRef>	POST /ref
getRef	(gateway, refId) => Promise<PaymentRefSnapshot>	GET /ref/:refId
listPaymentRefs	(options) => Promise<PaymentRefList>	GET /ref
revokePaymentRef	(options) => Promise<RevokedPaymentRef>	POST /ref/:refId/revoke
revokePayTo	(options) => Promise<RevokedPayTo>	POST /payto/:payTo/revoke

创建参数

TypeScript
1interface CreatePaymentRefOptions {2  gateway: string;3  payTo: string;4  network: string;5  asset?: 'USDC';6  amount?: string;7  invoiceId?: string;8  notifyUrl?: string;9  label?: string;10  description?: string;11  expiresInSecs?: number;12  apiKey?: string;13}

字段	校验规则
gateway	规范 HTTPS origin 或本地开发 origin
payTo	EVM address
asset	当前仅支持 USDC
amount	正的原子单位字符串；开放金额时省略
invoiceId	有界公开 id，且必须同时提供固定 amount
notifyUrl	公开 HTTPS 443 URL；低层 API 中需要 apiKey
label	最多 120 UTF-8 bytes
description	最多 512 UTF-8 bytes
expiresInSecs	正安全整数

返回模型

PaymentRef 包含 refId、refUrl 和不可变 snapshot。Snapshot 包含 schema 版本、network、payTo、asset、可选 amount、resource、invoice id、description、MIME type 和 expiry。

应把 snapshot 与业务记录一起保存，用于后续 receipt matching 和事件分析。

列表与撤销

listPaymentRefs 需要 gateway、payTo 和 apiKey，支持有界 limit 与不透明 cursor。列表项返回创建/过期时间及 active | revoked 状态。

撤销 ref 或退役 payTo 只会阻止后续授权，不会逆转已经上链的转账。历史结果必须从链状态和归档收据验证。