Skip to content

Receiver SDK

Create, inspect, list, and revoke PaymentRef records from receiver applications.

x402-paysdk/receive is intentionally small. It manages payment references and validates receiver-side inputs without taking on merchant order logic.

Create a reference

TypeScript
import { createPaymentRef } from 'x402-paysdk/receive';const ref = await createPaymentRef({  gateway: 'https://gateway.example',  payTo: '0x1111111111111111111111111111111111111111',  network: 'eip155:8453',  asset: 'USDC',  amount: '12500000',  label: 'Studio subscription',  description: 'July plan',  expiresInSecs: 3600,  apiKey: process.env.X402_API_KEY});console.log(ref.refUrl);

amount uses the token's smallest unit. 12_500_000 represents 12.5 USDC. Convert the returned refUrl to a QR code only at the presentation layer.

Lifecycle operations

  • getRef(gateway, refId) reads public ref metadata.
  • listPaymentRefs(options) returns a bounded merchant-scoped list.
  • revokePaymentRef(options) refuses future attempts against one ref.
  • revokePayTo(options) retires an address according to gateway policy.

notifyUrl requires merchant authentication and must be a public HTTPS endpoint. SDK validation rejects local, private, credential-bearing, or malformed URLs before sending the request.