Skip to content

Merchant SDK

Register merchants, manage refs and orders, verify notify events, issue refunds, and reconcile chain state.

x402-paysdk/merchant belongs on the backend. It works with merchant API keys, notify HMAC keys, wallet ownership proofs, orders, refunds, receipts, and reconciliation.

Register with payTo proof

  1. Call createMerchantChallenge() with the intended payTo, network, and webhook URL.
  2. Sign the returned message or typed data with the controlling merchant wallet.
  3. Call registerMerchant() with the challenge id and signature.
  4. Store the returned API key and notify HMAC key in a secrets manager; they are returned only once.

Create a client

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);

Fulfillment rule

Treat notify delivery as a low-latency hint. Before irreversible fulfillment, verify the signed receipt and required chain confirmations. Run reconcile() on a schedule because webhooks can be delayed or lost.

Order mode is optional. When enabled, use random refund intents and gateway-managed order APIs; do not authorize a refund from an unbound orderId or refundId query parameter.