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 Base wallet.

• 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 Token and Network

Currently only USDC on Base mainnet is supported:

Field	Value
token	USDC
network	BASE_MAINNET

Choose Your Flow

Flow A — Client-Side EIP-712 — Your code builds the EIP-712 typed data hash using ethers.js. More steps, but no additional round-trip to the facilitator.

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

Both flows produce a signed payment-signature header and submit it to POST /submit. The result is a sessionId confirming the payment was accepted.

If you are new to EIP-712 or EIP-3009, start with Flow B.

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