Complete payment flow

This guide builds the default stateless path. Your application owns its order record; the gateway owns references and protocol coordination; the chain and signed receipt provide payment evidence.

Prerequisites

• A deployed x402 gateway URL such as https://pay.example.com.
• A merchant-controlled EVM payTo wallet on the configured network.
• USDC using EIP-3009 on that network.
• A payer wallet adapter that can sign EIP-712 typed data.
• Backend secret storage for the merchant API key and notify HMAC key.

Install the single package in both applications and only import the entry point needed by that runtime:

Shell
1npm install x402-paysdk

1. Prove payTo ownership

Registration is a two-request challenge flow. The wallet signs a challenge bound to the gateway origin, action, payTo, network, nonce, and expiry.

TypeScript
1import {2  createMerchantChallenge,3  merchantChallengeTypedData,4  registerMerchant5} from 'x402-paysdk/merchant';67const gateway = 'https://pay.example.com';8const payTo = '0x1111111111111111111111111111111111111111';9const webhookUrl = 'https://merchant.example/x402/notify';1011const challenge = await createMerchantChallenge(gateway, {12  payTo,13  network: 'base',14  action: 'merchant.register',15  webhookUrl16});1718const signature = await merchantWallet.signTypedData(19  merchantChallengeTypedData(challenge.message)20);2122const credentials = await registerMerchant(gateway, {23  challengeId: challenge.challengeId,24  payTo,25  network: 'base',26  label: 'Example Store',27  webhookUrl,28  signature29});

Store apiKey, notifyHmacKey, and notifyHmacKeyId immediately in a secret manager. The gateway only returns raw credentials at issuance or rotation.

2. Create the merchant client

TypeScript
1import { MerchantClient } from 'x402-paysdk/merchant';23const merchant = new MerchantClient({4  gateway,5  apiKey: process.env.X402_API_KEY!,6  notifyHmacKey: process.env.X402_NOTIFY_KEY!,7  notifyHmacKeyId: process.env.X402_NOTIFY_KEY_ID!,8  payTo,9  network: 'base'10});

Create this client only on the backend. Do not serialize it, expose it through frontend state, or log its options.

3. Create and persist a PaymentRef

Amounts are atomic USDC units, so 24000000 means 24 USDC for a six-decimal token.

TypeScript
1import { createPaymentRef } from 'x402-paysdk/merchant';23const ref = await createPaymentRef(merchant, {4  payTo,5  network: 'base',6  asset: 'USDC',7  amount: '24000000',8  invoiceId: 'order_7K9M2',9  label: 'Order 7K9M2',10  description: 'Example Store checkout',11  expiresInSecs: 900,12  notifyUrl: webhookUrl13});1415await orders.savePaymentReference({16  orderId: 'order_7K9M2',17  refId: ref.refId,18  refUrl: ref.refUrl,19  expectedAmount: ref.snapshot.amount,20  expectedPayTo: ref.snapshot.payTo,21  expiresAt: ref.snapshot.expiresAt22});

Return only refUrl and display metadata to the payer application. The same URL can be transported as a link, QR code, deep link, or API payload.

4. Connect the payer wallet

The payer integration supplies a narrow signer. Private key material never enters the SDK.

TypeScript
1import type { WalletSigner } from 'x402-paysdk/pay';23const wallet: WalletSigner = {4  address: account.address,5  signTypedData: (typedData) => walletClient.signTypedData(typedData)6};

Before asking for a signature, you can inspect the signed requirements:

TypeScript
1import { getPaymentRequired } from 'x402-paysdk/pay';23const required = await getPaymentRequired(ref.refUrl);4const offer = required.accepts[0];56renderConfirmation({7  payTo: offer.payTo,8  amount: offer.amount,9  network: offer.network,10  asset: offer.asset11});

5. Authorize and settle

Use one unpredictable or business-unique paymentId for a single payment attempt. Reusing it with a different context must fail closed.

TypeScript
1import { pay } from 'x402-paysdk/pay';23const settlement = await pay({4  refUrl: ref.refUrl,5  paymentId: crypto.randomUUID(),6  wallet7});89console.log(settlement.txHash, settlement.receiptStatus);

pay() resolves the HTTPS receive URL, obtains 402 Payment Required, verifies the signed offer and gateway DID identity, builds EIP-3009 typed data, asks the wallet to sign, submits PAYMENT-SIGNATURE, and returns the settlement evidence.

6. Send evidence to the backend

The payer client should send the tx hash and complete signed receipt pair to your backend. Treat them as evidence to verify, not as a trusted “paid” flag.

TypeScript
1await fetch('/api/orders/order_7K9M2/payment', {2  method: 'POST',3  headers: { 'content-type': 'application/json' },4  body: JSON.stringify({5    txHash: settlement.txHash,6    signedReceipt: settlement.signedPaymentReceipt,7    receipt: settlement.receipt8  })9});

7. Verify receipt and chain finality

The backend binds verification to the order's stored expectations. Only fulfill after the signature, payment context, transfer, and confirmation policy all pass.

TypeScript
1import { verifyReceipt } from 'x402-paysdk/merchant';23const verification = await verifyReceipt(merchant, {4  signedReceipt,5  receipt,6  expectedPayTo: order.expectedPayTo,7  expectedAmount: order.expectedAmount,8  minConfirmations: 39});1011if (!verification.valid || !verification.confirmed) {12  throw new Error(verification.reason ?? 'payment is not final');13}1415await orders.markPaidOnce(order.id, {16  txHash: verification.txHash!,17  payer: verification.payer!,18  receipt19});

The markPaidOnce operation belongs in your database and should be atomic. The default gateway intentionally does not own merchant fulfillment state.

8. Add notify as a fast hint

Read the exact raw request body before JSON parsing and use shared atomic nonce storage in multi-instance production.

TypeScript
1import { verifySettlementNotify } from 'x402-paysdk/merchant';23const result = await verifySettlementNotify(4  request.headers,5  rawBody,6  { [process.env.X402_NOTIFY_KEY_ID!]: process.env.X402_NOTIFY_KEY! },7  sharedNonceStore8);910if (!result.ok) return new Response('invalid notify', { status: 401 });1112await paymentQueue.enqueue(result.notify);13return new Response(null, { status: 204 });

Notify can trigger verification sooner, but it is never financial finality. The queued worker must still call receipt or tx verification.

Completion criteria

• The payer saw the exact payTo, amount, network, and asset before signing.
• The signed offer was trusted through pinned signers or same-origin DID discovery.
• The backend matched the receipt to its stored order expectations.
• The chain transfer reached the configured confirmation policy.
• Fulfillment used a single atomic state transition.
• Credentials, payment signatures, and raw notify bodies were not logged.

Continue with production operations for recovery and reconciliation.