Payment Flow

The x402 flow has three phases: Initiate → Sign → Submit. There are three integration flows depending on your chain/token combination and how much EIP-712 logic you want to handle yourself.

Flow	Strategy	When to use
A — Client-Side EIP-712	EIP-3009	USDC on Base / Polygon / Lisk — you build the hash locally
B — Facilitator-Assisted	EIP-3009	USDC on Base / Polygon / Lisk — facilitator builds the hash
C — Permit2	Permit2	BSC, Ethereum, or any non-USDC token

Check Supported Assets if you are unsure which applies to your chain/token.

---

Flow A — Client-Side EIP-712

Use this flow when you are on a USDC EIP-3009 chain (Base, Polygon, Lisk) and want full control over signing without an extra /build call.

What you need before starting

npm install ethers

import { ethers } from 'ethers';

const BASE_URL    = 'https://facilitator.ivorypay.io';
const API_KEY     = process.env.IVORYPAY_API_KEY;
const PRIVATE_KEY = process.env.EVM_PRIVATE_KEY;

---

Step 1 — Initiate the payment

const initiateRes = await fetch(`${BASE_URL}/api/x402/initiate`, {
  method: 'POST',
  headers: { 'Authorization': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    amount: 0.01,
    token: 'USDC',
    network: 'BASE_MAINNET',
    resourceUrl: 'https://yourapp.com/premium-content',
    resourcesDescription: 'Access to premium content',
  }),
});

const initiateBody = await initiateRes.json();

The response body:

{
  "statusCode": 402,
  "headers": { "PAYMENT-REQUIRED": "<base64-encoded-json>" },
  "body": { ... }
}

---

Step 2 — Decode the payment requirement

const paymentRequired = JSON.parse(
  Buffer.from(initiateBody.headers['PAYMENT-REQUIRED'], 'base64').toString('utf8')
);

const accepted = paymentRequired.accepts[0];

// accepted contains:
// {
//   scheme: 'exact',
//   network: 'eip155:8453',
//   amount: '0.01',
//   asset: '0xUSDCContractAddress',
//   payTo: '0xFacilitatorAddress',
//   maxTimeoutSeconds: 60,
//   extra: { name: 'USDC', version: '2' }
// }

---

Step 3 — Build the EIP-712 typed data hash locally

const EIP3009_TRANSFER_TYPES = {
  TransferWithAuthorization: [
    { name: 'from',        type: 'address' },
    { name: 'to',          type: 'address' },
    { name: 'value',       type: 'uint256' },
    { name: 'validAfter',  type: 'uint256' },
    { name: 'validBefore', type: 'uint256' },
    { name: 'nonce',       type: 'bytes32' },
  ],
};

const wallet  = new ethers.Wallet(PRIVATE_KEY);
const chainId = parseInt(accepted.network.split(':')[1]); // 'eip155:8453' → 8453

const now         = Math.floor(Date.now() / 1000);
const validAfter  = now;
const validBefore = now + accepted.maxTimeoutSeconds;
const nonce       = ethers.hexlify(ethers.randomBytes(32)); // random bytes32

const domain = {
  name:              accepted.extra.name,    // 'USDC'
  version:           accepted.extra.version, // '2'
  chainId:           chainId,
  verifyingContract: accepted.asset,
};

const message = {
  from:        ethers.getAddress(wallet.address),
  to:          ethers.getAddress(accepted.payTo),
  value:       BigInt(Math.round(parseFloat(accepted.amount) * 1_000_000)), // 6 decimals
  validAfter:  BigInt(validAfter),
  validBefore: BigInt(validBefore),
  nonce:       nonce,
};

const typedDataHash = ethers.TypedDataEncoder.hash(domain, EIP3009_TRANSFER_TYPES, message);

---

Step 4 — Sign the hash

const sig = wallet.signingKey.sign(typedDataHash);

const signature =
  '0x' +
  sig.r.slice(2) +
  sig.s.slice(2) +
  Buffer.from([sig.v]).toString('hex');

---

Step 5 — Build the payment-signature header

const signaturePayload = {
  x402Version: 2,
  resource: paymentRequired.resource,
  accepted: {
    scheme:            accepted.scheme,
    network:           accepted.network,
    amount:            accepted.amount,
    asset:             accepted.asset,
    payTo:             accepted.payTo,
    maxTimeoutSeconds: accepted.maxTimeoutSeconds,
    extra:             accepted.extra,
  },
  payload: {
    signature: signature,
    authorization: {
      from:        wallet.address,
      to:          accepted.payTo,
      value:       accepted.amount,
      validAfter:  String(validAfter),
      validBefore: String(validBefore),
      nonce:       nonce,
    },
  },
};

const paymentSignatureHeader = Buffer.from(
  JSON.stringify(signaturePayload), 'utf8'
).toString('base64');

---

Step 6 — Submit the payment

const submitRes = await fetch(`${BASE_URL}/api/x402/submit`, {
  method: 'POST',
  headers: {
    'Authorization':     API_KEY,
    'payment-signature': paymentSignatureHeader,
  },
});

const result = await submitRes.json();
console.log(result.sessionId);

---

Flow B — Facilitator-Assisted Build

Use this flow for USDC on EIP-3009 chains when you want the facilitator to compute the hash. Steps 1–2 and 4–6 are identical to Flow A; only Step 3 differs.

Step 3 — Call /build to get the typed data hash

const wallet      = new ethers.Wallet(PRIVATE_KEY);
const now         = Math.floor(Date.now() / 1000);
const validBefore = now + accepted.maxTimeoutSeconds;
const nonce       = ethers.hexlify(ethers.randomBytes(32));

const buildRes = await fetch(`${BASE_URL}/api/x402/build`, {
  method: 'POST',
  headers: { 'Authorization': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    to:          accepted.payTo,
    from:        wallet.address,
    nonce:       nonce,
    validBefore: validBefore,
  }),
});

const buildBody = await buildRes.json();

// buildBody:
// {
//   typedDataHash: '0x...',
//   validAfter: 1700000000,
//   from: '0x...',
//   to: '0x...',
//   amount: 0.01,
//   chain: 'BASE_MAINNET',
//   token: 'USDC',
//   spender: '0x...'   ← only relevant for Permit2 chains
// }

const { typedDataHash, validAfter } = buildBody;

Sign and submit exactly as in Flow A Steps 4–6, using validAfter from the /build response.

---

Flow C — Permit2 Signing

Use this flow for BSC, Ethereum, or any non-USDC token (e.g. USDT on BSC). The server uses Uniswap's Permit2 contract instead of EIP-3009.

One-time prerequisite: Before the first Permit2 payment, the payer wallet must approve the Permit2 contract to spend their tokens. See Permit2 Approval.

What you need before starting

npm install ethers

import { ethers } from 'ethers';

const BASE_URL    = 'https://facilitator.ivorypay.io';
const API_KEY     = process.env.IVORYPAY_API_KEY;
const PRIVATE_KEY = process.env.EVM_PRIVATE_KEY;

const PERMIT2_ADDRESS = '0x000000000022D473030F116dDEE9F6B43aC78BA3';

---

Step 1 — Initiate the payment

Same as the other flows. Pass the correct token and network for your chain.

const initiateRes = await fetch(`${BASE_URL}/api/x402/initiate`, {
  method: 'POST',
  headers: { 'Authorization': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    amount: 0.01,
    token: 'USDT',
    network: 'BSC_MAINNET',
    resourceUrl: 'https://yourapp.com/premium-content',
    resourcesDescription: 'Access to premium content',
  }),
});

const initiateBody = await initiateRes.json();

---

Step 2 — Decode the payment requirement

const paymentRequired = JSON.parse(
  Buffer.from(initiateBody.headers['PAYMENT-REQUIRED'], 'base64').toString('utf8')
);

const accepted = paymentRequired.accepts[0];

---

Step 3 — Call /build to get the typed data hash and spender

For Permit2, always call /build — you need the spender address (the gas-payer vault EOA) that the server assigns. This must be included in the signed message.

const wallet      = new ethers.Wallet(PRIVATE_KEY);
const now         = Math.floor(Date.now() / 1000);
const validBefore = now + accepted.maxTimeoutSeconds;
const nonce       = ethers.hexlify(ethers.randomBytes(32));

const buildRes = await fetch(`${BASE_URL}/api/x402/build`, {
  method: 'POST',
  headers: { 'Authorization': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    to:          accepted.payTo,
    from:        wallet.address,
    nonce:       nonce,
    validBefore: validBefore,
  }),
});

const buildBody = await buildRes.json();

// buildBody:
// {
//   typedDataHash: '0x...',
//   validAfter: 1700000000,
//   from: '0x...',
//   to: '0x...',
//   amount: 0.01,
//   chain: 'BSC_MAINNET',
//   token: 'USDT',
//   spender: '0xGasPayerVaultAddress'   ← required for Permit2 signing
// }

const { typedDataHash, validAfter, spender } = buildBody;

---

Step 4 — Build the Permit2 typed data hash locally

The Permit2 domain has no version field. The nonce is a uint256 (not bytes32). The signed struct uses deadline instead of validBefore, and there is no validAfter in the signed data.

const PERMIT2_TRANSFER_TYPES = {
  PermitTransferFrom: [
    { name: 'permitted', type: 'TokenPermissions' },
    { name: 'spender',   type: 'address' },   // gas-payer vault from /build
    { name: 'nonce',     type: 'uint256' },   // uint256, not bytes32
    { name: 'deadline',  type: 'uint256' },   // = validBefore
  ],
  TokenPermissions: [
    { name: 'token',  type: 'address' },
    { name: 'amount', type: 'uint256' },
  ],
};

const chainId    = parseInt(accepted.network.split(':')[1]); // 'eip155:56' → 56
const decimals   = 18; // USDT on BSC uses 18 decimals; check /build response for your token
const value      = BigInt(Math.round(parseFloat(accepted.amount) * Math.pow(10, decimals)));

const domain = {
  name:              'Permit2',
  chainId:           chainId,
  verifyingContract: PERMIT2_ADDRESS,
  // No `version` field — Permit2 domain intentionally omits it
};

const message = {
  permitted: {
    token:  ethers.getAddress(accepted.asset),  // the token contract address
    amount: value,
  },
  spender:  ethers.getAddress(spender),          // gas-payer vault from /build
  nonce:    BigInt(nonce),                        // cast to uint256
  deadline: BigInt(validBefore),                  // = validBefore; no validAfter here
};

const permit2Hash = ethers.TypedDataEncoder.hash(domain, PERMIT2_TRANSFER_TYPES, message);

Important: The hash returned by /build already encodes these parameters server-side. You can use buildBody.typedDataHash directly instead of computing the hash yourself — the result must be identical. If you compute it locally, ensure your domain, types, and message exactly match the above.

---

Step 5 — Sign the hash

Identical to EIP-3009 signing. Use the hash from /build (or your locally computed one if you verified they match).

const sig = wallet.signingKey.sign(buildBody.typedDataHash);

const signature =
  '0x' +
  sig.r.slice(2) +
  sig.s.slice(2) +
  Buffer.from([sig.v]).toString('hex');

---

Step 6 — Build the payment-signature header and submit

The payment-signature header structure is the same as for EIP-3009.

const signaturePayload = {
  x402Version: 2,
  resource: paymentRequired.resource,
  accepted: {
    scheme:            accepted.scheme,
    network:           accepted.network,
    amount:            accepted.amount,
    asset:             accepted.asset,
    payTo:             accepted.payTo,
    maxTimeoutSeconds: accepted.maxTimeoutSeconds,
    extra:             accepted.extra,
  },
  payload: {
    signature: signature,
    authorization: {
      from:        wallet.address,
      to:          accepted.payTo,
      value:       accepted.amount,
      validAfter:  String(validAfter),   // from /build response
      validBefore: String(validBefore),
      nonce:       nonce,
    },
  },
};

const paymentSignatureHeader = Buffer.from(
  JSON.stringify(signaturePayload), 'utf8'
).toString('base64');

const submitRes = await fetch(`${BASE_URL}/api/x402/submit`, {
  method: 'POST',
  headers: {
    'Authorization':     API_KEY,
    'payment-signature': paymentSignatureHeader,
  },
});

const result = await submitRes.json();
console.log(result.sessionId);

---

Verify a Payment Reference

After a successful submit you receive a sessionId. Use the verify endpoint to retrieve on-chain proof:

const verifyRes = await fetch(`${BASE_URL}/api/x402/verify/${reference}`, {
  method: 'POST',
  headers: { 'Authorization': API_KEY },
});

const verifyBody = await verifyRes.json();

const paymentResponse = JSON.parse(
  Buffer.from(verifyBody.headers['PAYMENT-RESPONSE'], 'base64').toString('utf8')
);

// {
//   success: true,
//   transaction: '0xTxHash',
//   network: 'eip155:56',
//   payer: '0xPayerAddress'
// }