Payment Flow

The x402 flow has three phases: Initiate → Sign → Submit. The difference between the two integration flows is only in the Sign phase — how you obtain and compute the typed data hash that the wallet signs.

---

Flow A — Client-Side EIP-712

Use this flow when you want full control over the signing process and prefer not to make the extra /build request. You construct the EIP-712 domain and message yourself using ethers.js.

What you need before starting

npm install ethers

import { ethers } from 'ethers';
import fetch from 'node-fetch'; // or use the built-in fetch in Node 18+

const BASE_URL   = 'https://facilitator.ivorypay.io';
const API_KEY    = process.env.IVORYPAY_API_KEY;  // your merchant API key
const PRIVATE_KEY = process.env.EVM_PRIVATE_KEY;  // payer wallet private key

---

Step 1 — Initiate the payment

Tell the facilitator what resource you are charging for. The response gives you the payment terms the wallet must agree to.

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,                                        // decimal USDC — 0.01 = 1 cent
    token: 'USDC',
    network: 'BASE_MAINNET',
    resourceUrl: 'https://yourapp.com/premium-content', // the resource being paid for
    resourcesDescription: 'Access to premium content',
  }),
});

const initiateBody = await initiateRes.json();

The response body looks like this:

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

---

Step 2 — Decode the payment requirement

The PAYMENT-REQUIRED header value is a base64-encoded JSON string. Decode it to get the payment terms.

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

// Always use the first accepted payment option
const accepted = paymentRequired.accepts[0];

// accepted contains:
// {
//   scheme: 'exact',
//   network: 'eip155:8453',       ← Base mainnet chain ID is 8453
//   amount: '0.01',               ← string decimal USDC
//   asset: '0xTokenContractAddress',
//   payTo: '0xFacilitatorAddress',
//   maxTimeoutSeconds: 60,
//   extra: { name: 'USDC', version: '2' }
// }

---

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

This is where Flow A differs from Flow B. You construct the domain, message, and hash yourself.

// The EIP-3009 typed data structure for TransferWithAuthorization
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);

// Parse the chain ID from the network string — 'eip155:8453' → 8453
const chainId = parseInt(accepted.network.split(':')[1]);

// Time window: the authorization is valid from `validAfter` to `validBefore`
const now         = Math.floor(Date.now() / 1000);
const validAfter  = now;
const validBefore = now + accepted.maxTimeoutSeconds; // e.g. now + 60

// A random 32-byte nonce prevents replay attacks
const nonce = ethers.hexlify(ethers.randomBytes(32));

// EIP-712 domain — identifies the token contract the authorization is for
const domain = {
  name:              accepted.extra.name,    // 'USDC'
  version:           accepted.extra.version, // '2'
  chainId:           chainId,                // 8453
  verifyingContract: accepted.asset,         // token contract address
};

// The authorization message — convert decimal USDC to micro-USDC (6 decimals)
const message = {
  from:        ethers.getAddress(wallet.address),
  to:          ethers.getAddress(accepted.payTo),
  value:       BigInt(Math.round(parseFloat(accepted.amount) * 1_000_000)), // e.g. 0.01 → 10000n
  validAfter:  BigInt(validAfter),
  validBefore: BigInt(validBefore),
  nonce:       nonce,
};

// Compute the EIP-712 hash
const typedDataHash = ethers.TypedDataEncoder.hash(domain, EIP3009_TRANSFER_TYPES, message);

---

Step 4 — Sign the hash

Sign the raw hash using the wallet's ECDSA private key. This does not use eth_signTypedData — it signs the raw bytes directly. The signature is encoded as 65 bytes: r (32) + s (32) + v (1).

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

// Encode as 0x-prefixed 65-byte hex: r[32] + s[32] + v[1]
const signature =
  '0x' +
  sig.r.slice(2) +  // r is already '0x...' — strip the prefix
  sig.s.slice(2) +  // same for s
  Buffer.from([sig.v]).toString('hex'); // v is a small integer (27 or 28)

---

Step 5 — Build the payment-signature header

Package the signature and authorization details into an X402SignaturePayload object, JSON-encode it, then base64-encode the result.

const signaturePayload = {
  x402Version: 2,
  resource: paymentRequired.resource, // pass through from initiate response
  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,         // decimal string, e.g. '0.01'
      validAfter:  String(validAfter),      // unix timestamp string
      validBefore: String(validBefore),     // unix timestamp string
      nonce:       nonce,
    },
  },
};

// Base64-encode for the header
const paymentSignatureHeader = Buffer.from(
  JSON.stringify(signaturePayload),
  'utf8'
).toString('base64');

---

Step 6 — Submit the payment

Send the signed payload to the submit endpoint. A 201 response with a sessionId confirms the payment was accepted and the on-chain transfer has been initiated.

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); // e.g. 'sess_abc123'

---

Flow B — Facilitator-Assisted Build

Use this flow when you want to avoid constructing the EIP-712 domain yourself. The facilitator's /build endpoint computes the typed data hash for you — you only need to sign the hash it returns.

Flow B has the same Step 1 (Initiate) and Steps 4–6 (Sign + Submit) as Flow A. The difference is Step 2/3: instead of building the hash locally, you ask the facilitator to build it.

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

Identical to Flow A Step 1.

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

---

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

Instead of constructing the EIP-712 hash yourself, send the key parameters to the facilitator and it returns the hash ready to sign. You still generate the nonce and validBefore — this keeps the randomness and time window in your hands.

const wallet = new ethers.Wallet(PRIVATE_KEY);

const now         = Math.floor(Date.now() / 1000);
const validBefore = now + accepted.maxTimeoutSeconds; // e.g. now + 60
const nonce       = ethers.hexlify(ethers.randomBytes(32)); // random 32 bytes

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,    // facilitator's receiving address
    from:        wallet.address,    // payer wallet address
    nonce:       nonce,
    validBefore: validBefore,       // unix timestamp (number)
  }),
});

const buildBody = await buildRes.json();

// buildBody contains:
// {
//   typedDataHash: '0x...',   ← sign this
//   validAfter: 1700000000,   ← use this when building the signature payload
//   from: '0x...',
//   to: '0x...',
//   amount: 0.01,
//   chain: 'eip155:8453',
//   token: 'USDC'
// }

const { typedDataHash, validAfter } = buildBody;

---

Step 4 — Sign the hash

Same as Flow A Step 4. Sign the hash returned by /build.

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

Same structure as Flow A Step 5. Use validAfter from the /build response (not a locally computed timestamp).

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), // what you sent to /build
      nonce:       nonce,               // what you sent to /build
    },
  },
};

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

---

Step 6 — Submit the payment

Identical to Flow A Step 6.

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. If you need to later confirm on-chain proof or share the result with another system, use the verify endpoint:

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

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