Receiver API

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

The receiver entry point manages payment references. It does not sign payer payments, hold merchant order state, or verify fulfillment.

Functions

Function	Signature	Gateway route
createPaymentRef	(options: CreatePaymentRefOptions) => Promise<PaymentRef>	POST /ref
getRef	(gateway: string, refId: string) => Promise<PaymentRefSnapshot>	GET /ref/:refId
listPaymentRefs	(options: ListPaymentRefsOptions) => Promise<PaymentRefList>	GET /ref
revokePaymentRef	(options: RevokePaymentRefOptions) => Promise<RevokedPaymentRef>	POST /ref/:refId/revoke
revokePayTo	(options: RevokePayToOptions) => Promise<RevokedPayTo>	POST /payto/:payTo/revoke

Create options

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}

Field	Validation
gateway	Canonical HTTPS origin or local development origin
payTo	EVM address
network	Supported network name
asset	Currently USDC only
amount	Positive atomic decimal string; omit for open amount
invoiceId	Bounded public id and requires fixed amount
notifyUrl	Public HTTPS URL on port 443; requires apiKey in this low-level API
label	At most 120 UTF-8 bytes
description	At most 512 UTF-8 bytes
expiresInSecs	Positive safe integer
apiKey	Bearer credential when the gateway requires merchant auth

Return model

TypeScript
1interface PaymentRef {2  refId: string;3  refUrl: string;4  snapshot: {5    v: 2;6    scheme: 'exact';7    network: string;8    payTo: string;9    asset: 'USDC';10    amount?: string;11    resource: string;12    invoiceId?: string;13    description?: string;14    mimeType: string;15    expiresAt?: number;16  };17}

Persist the immutable snapshot with the business record. It is the expected payment context used for receipt matching and incident analysis.

Listing

listPaymentRefs requires gateway, payTo, and apiKey. limit is a positive safe integer and cursor must be the exact opaque value returned by the gateway.

Each item contains ref id, payTo, network, asset, optional amount/invoice/label, creation and expiry times, and active | revoked status.

Revocation behavior

Revoking a ref prevents future authorization through that ref. Retiring a payTo prevents future use according to gateway policy. Neither operation reverses an already mined transfer; verify historical settlement from chain state and archived receipts.