Quickstart

This page gets you set up from zero to a working payment submission in the shortest path possible.

Prerequisites

You need:

• A merchant API key — issued by the Ivorypay team.

• An EVM wallet private key — the wallet that will sign the payment authorization. In production this is your customer's wallet; in testing it can be any funded wallet on the target chain.

• Node.js 18+ with npm or yarn.

Install Dependencies

The only external package required is ethers.js v6 for EIP-712 signing:

npm install ethers

If you are using TypeScript, ethers ships its own types — no extra @types package needed.

Environment Variables

Store sensitive values in environment variables, never in source code:

# .env
IVORYPAY_API_KEY=your_merchant_api_key_here
EVM_PRIVATE_KEY=0xYourWalletPrivateKey

Load them at runtime (Node.js example using dotenv):

npm install dotenv

import 'dotenv/config';

const API_KEY = process.env.IVORYPAY_API_KEY;
const PRIVATE_KEY = process.env.EVM_PRIVATE_KEY;

Base URL

https://facilitator.ivorypay.io

Set it as a constant so you only change it in one place if your environment changes:

const BASE_URL = 'https://facilitator.ivorypay.io';

Supported Chains and Tokens

Ivorypay x402 works across multiple EVM mainnets. The server automatically selects the transfer strategy based on the chain and token you specify. See Supported Assets for the full matrix.

Quick reference:

Chain	Token	Strategy
Base, Polygon, Lisk	USDC	EIP-3009
BSC, Ethereum	USDC or USDT	Permit2
Any chain	Non-USDC token	Permit2

Permit2 Approval (Required for BSC, Ethereum, and Non-USDC Tokens)

If your integration uses a Permit2 chain or token (see table above), the payer wallet must run a one-time ERC-20 approval before any payment can succeed.

This is not per-transaction — it only needs to be done once per wallet/token/chain combination. Without it, the server will reject the submission with an allowance error.

See Permit2 Approval for the complete guide and runnable code.

Choose Your Flow

Flow A — Client-Side EIP-712 — Your code builds the EIP-712 hash for EIP-3009 using ethers.js. No extra API call.

Flow B — Facilitator-Assisted Build — The facilitator builds and returns the EIP-3009 hash via POST /build. Simpler code, one extra HTTP call.

Flow C — Permit2 Signing — For BSC, Ethereum, or any non-USDC token. Always calls /build to get the spender address, then signs with Permit2 typed data.

If you are unsure which flow to use, check Supported Assets for your chain/token combination. If it is new to EIP-712, start with Flow B for EIP-3009 chains or Flow C for Permit2 chains.

Head to Payment Flow for the full step-by-step code.