Accept Payment

Use this endpoint to generate a payment request — a record your customer pays against. IvoryPay supports two payment channels:

• CRYPTO — customer sends cryptocurrency to a blockchain address

• FIAT — customer makes a bank transfer to a collection account

Base path: /v1/transactions Authentication: API Key (Authorization: <secret-key>)

---

Endpoints

Method	Path	Auth	Description
POST	/v1/transactions	API Key	Create a payment collection request
GET	/v1/transactions/:reference/verify	Public	Verify payment status by reference

---

POST /v1/transactions

Creates a new incoming payment request. The type field determines whether IvoryPay returns a crypto address or a bank account for the customer to pay into.

Request

Headers

Authorization: <your-secret-api-key>
Content-Type: application/json

Body Parameters

Field	Type	Required	Description
amount	number	Yes	Amount in the baseFiat currency. Must be >= 0.
email	string	Yes	Customer's email address. Used for notifications.
firstName	string	No	Customer's first name.
lastName	string	No	Customer's last name.
type	string	Yes	Payment channel — CRYPTO or FIAT.
mode	string	Yes	Integration mode — API for programmatic integrations, CHECKOUT to use the IvoryPay hosted checkout page.
baseFiat	string	Yes	The fiat currency amount is expressed in. See supported currencies.
crypto	string	Yes	Crypto token associated with the payment. See supported tokens.
chain	string	CRYPTO (API mode only)	Required when type is CRYPTO and mode is API. Not required in CHECKOUT mode. See chains.
reference	string	Yes	A UUID you supply for idempotency and reconciliation.
redirect_url	string	No	A URL the customer is redirected to after a successful payment. Only used in CHECKOUT mode.
metadata	string	No	Any JSON string stored on the transaction. Returned as-is in webhooks.

chain is not required for FIAT payments or when mode is CHECKOUT.

---

CRYPTO Payment

The customer sends cryptocurrency directly to a blockchain address.

Request

{
  "amount": 1000,
  "type": "CRYPTO",
  "chain": "BSC_TESTNET",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[e-mail]",
  "reference": "550e8400-e29b-41d4-a716-446655440000",
  "baseFiat": "NGN",
  "mode": "API",
  "crypto": "USDT"
}

Response

{
  "success": true,
  "message": "Transaction was initiated successfully",
  "data": {
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "collectionDetails": {
      "network": "BSC_MAINNET",
      "address": "0x5020D82d223ffC7Ae770af32eD91d7Af9Fd1adEd"
    },
    "amountInCrypto": 1005,
    "amountInFiat": 1361536.743846,
    "fiatCurrency": "NGN",
    "platformFeeInCrypto": 5,
    "channel": "CRYPTO",
    "email": "[e-mail]",
    "currency": "USDT",
    "validityPeriod": 600,
    "expiresAt": "2026-02-19T15:22:02.773Z"
  }
}

What to do with the response:

• Display collectionDetails.address as the wallet address your customer sends funds to

• Display amountInCrypto as the exact amount they must send (fee already included)

• platformFeeInCrypto is IvoryPay's fee included in amountInCrypto

• Payment window expires at expiresAt (validityPeriod = 600 seconds) — display a countdown timer

• Store reference for order reconciliation and webhook matching

CRYPTO Payment Mismatches and Refunds

For crypto collections, the customer should send the exact amountInCrypto in the selected currency/token to the returned wallet address.

Scenario	Outcome
Underpayment	The transaction fails and the received funds are refunded to the customer.
Overpayment	The transaction succeeds and the excess amount is refunded to the customer.
Token mismatch	The transaction fails and the received funds are refunded to the customer.

---

FIAT Payment

IvoryPay assigns a virtual bank account your customer pays into via bank transfer. The payment is then settled in the configured crypto token.

Request

{
  "amount": 1000,
  "email": "[e-mail]",
  "firstName": "John",
  "lastName": "Doe",
  "type": "FIAT",
  "mode": "API",
  "baseFiat": "NGN",
  "crypto": "USDT",
  "reference": "ecb1d467-eaa4-4640-ac61-1a777c86f67a"
}

Response

{
  "success": true,
  "message": "Transaction was initiated successfully",
  "data": {
    "reference": "ecb1d467-eaa4-4640-ac61-1a777c86f67a",
    "collectionDetails": {
      "accountName": "Dreambill Limited",
      "accountNumber": "6873451235",
      "bankName": "GTBank"
    },
    "amountInFiat": 10010,
    "fiatCurrency": "NGN",
    "platformFeeInFiat": 10,
    "channel": "FIAT",
    "email": "[e-mail]",
    "currency": "USDT",
    "validityPeriod": 600
  }
}

What to do with the response:

• Display collectionDetails.bankName, collectionDetails.accountNumber, and collectionDetails.accountName to your customer

• Display amountInFiat as the exact amount they must transfer (match this to the kobo/cent)

• The payment window is validityPeriod seconds (600 = 10 minutes) — display a countdown timer

• Store reference for reconciliation; listen to webhooks for settlement confirmation

The customer must transfer exactly amountInFiat in fiatCurrency. Sending a different amount may cause a mismatch.

---

CHECKOUT Mode

Use mode: CHECKOUT to redirect your customer to the IvoryPay hosted checkout page instead of building your own payment UI. IvoryPay handles the payment flow — your customer selects the payment type, completes the payment, and is redirected back to your site.

• chain is not required — the customer selects a network on the checkout page

• redirect_url is optional — if provided, the customer is redirected there after a successful payment with the reference appended as a query parameter

Request

{
  "amount": 5000,
  "email": "[e-mail]",
  "firstName": "John",
  "lastName": "Doe",
  "type": "CRYPTO",
  "mode": "CHECKOUT",
  "baseFiat": "NGN",
  "crypto": "USDT",
  "reference": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "redirect_url": "https://yoursite.com/order/success"
}

Response

{
  "success": true,
  "message": "Transaction was initiated successfully",
  "data": {
    "reference": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "checkoutUrl": "https://checkout.ivorypay.io/checkout/f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "channel": "CRYPTO",
    "status": "PENDING"
  }
}

Redirect your customer to checkoutUrl. After a successful payment, they will be sent to:

https://yoursite.com/order/success?reference=f47ac10b-58cc-4372-a567-0e02b2c3d479

You can then call GET /v1/transactions/:reference/verify server-side to confirm the payment before fulfilling the order.

---

CRYPTO vs FIAT — Response Comparison

Field	CRYPTO	FIAT
channel	"CRYPTO"	"FIAT"
collectionDetails.address	Blockchain wallet address to send funds to	—
collectionDetails.network	Blockchain network (e.g. BSC_MAINNET)	—
collectionDetails.accountName	—	Beneficiary account name
collectionDetails.accountNumber	—	Beneficiary account number
collectionDetails.bankName	—	Beneficiary bank name
amountInCrypto	Exact crypto amount to send (fee included)	—
platformFeeInCrypto	IvoryPay's fee included in amountInCrypto	—
amountInFiat	Fiat equivalent of the crypto amount	Exact bank transfer amount
fiatCurrency	Fiat currency of amountInFiat	Currency of bank transfer (NGN, etc.)
platformFeeInFiat	—	IvoryPay's fee included in amountInFiat
validityPeriod	Seconds until payment window closes (600)	Seconds until payment window closes (600)
expiresAt	ISO timestamp when the payment window closes	—

---

Error Responses

Status	Message	Cause
400	amount must not be less than 0	Negative amount
400	email must be an email	Invalid email format
400	type must be one of FIAT, CRYPTO	Invalid type value
400	network chain must be one of ...	Invalid or missing chain for CRYPTO
401	Unauthorized	Missing or invalid API key

---

GET /v1/transactions/:reference/verify

Verifies the current payment status of a transaction by reference. This endpoint is public — no API key required. Use it from your frontend or backend to confirm a customer payment.

Request

Path Parameters

Parameter	Type	Description
reference	string	Transaction reference string

Example

GET /v1/transactions/ecb1d467-eaa4-4640-ac61-1a777c86f67a/verify

Response

{
  "success": true,
  "message": "Verification successful",
  "data": {
    "reference": "ecb1d467-eaa4-4640-ac61-1a777c86f67a",
    "status": "SUCCESS",
    "channel": "FIAT",
    "settledAmountInCrypto": 0.9912,
    "currency": "USDT",
    "completedAt": "2026-02-19T10:14:32.000Z"
  }
}

---

Supported Values

baseFiat

Value	Currency
NGN	Nigerian Naira
USD	US Dollar

crypto (token)

Value	Name
USDT	Tether USD
USDC	USD Coin

chain (network)

Required for CRYPTO payments only.

Value	Network Name	Standard
BSC_MAINNET	Binance Smart Chain (BNB Chain)	BEP-20
POLYGON	Polygon (Matic Network)	ERC-20

---

Transaction Lifecycle

PENDING → PROCESSING → CONFIRMING → SUCCESS
                                  ↘ MISMATCH   (underpayment or token mismatch)
                                  ↘ EXPIRED    (payment window closed)
                                  ↘ FAILED

Status	Description
PENDING	Transaction created, waiting for the customer to pay
PROCESSING	Payment detected, being processed
CONFIRMING	Awaiting sufficient confirmations
SUCCESS	Payment confirmed, funds credited to your wallet
MISMATCH	Customer sent less than expected or sent the wrong token
EXPIRED	Payment window closed with no payment received
FAILED	Transaction failed

For FIAT payments, the validityPeriod (600 seconds) defines how long the bank account assignment remains active. Expired transactions are not retried — create a new transaction instead. For CRYPTO payments, underpayments and token mismatches fail and are refunded to the customer. Overpayments succeed, and only the excess amount is refunded.

---

Integration Flow

CRYPTO

1. Customer initiates checkout on your platform
2. POST /v1/transactions (type: CRYPTO)  →  receive address + expectedAmountInCrypto
3. Display the wallet address and exact crypto amount to the customer
4. Customer sends the exact amount on-chain
5. IvoryPay detects payment → fires webhook to your server
6. Receive cryptoCollection.success webhook → fulfill the order
   (or poll GET /v1/transactions/:reference/verify as a fallback)

FIAT

1. Customer initiates checkout on your platform
2. POST /v1/transactions (type: FIAT)  →  receive collectionDetails + amountInFiat
3. Display the bank name, account number, and exact NGN amount to the customer
4. Start a countdown from validityPeriod (600 seconds)
5. Customer makes a bank transfer for exactly amountInFiat
6. IvoryPay confirms the transfer → fires webhook to your server
7. Receive fiatCollection.success webhook → fulfill the order
   (or poll GET /v1/transactions/:reference/verify as a fallback)

---

Code Examples

Node.js — FIAT

const axios = require('axios');
const { randomUUID } = require('crypto');

const BASE_URL = 'https://api.ivorypay.io/api/v1';
const reference = randomUUID();

// Step 1: Create FIAT payment request
const response = await axios.post(
  `${BASE_URL}/transactions`,
  {
    amount: 1000,
    email: '[e-mail]',
    type: 'FIAT',
    mode: 'API',
    baseFiat: 'NGN',
    crypto: 'USDT',
    reference,
  },
  {
    headers: { Authorization: process.env.IVORYPAY_SECRET_KEY },
  },
);

const { collectionDetails, amountInFiat, fiatCurrency, validityPeriod } =
  response.data.data;

console.log(`Bank: ${collectionDetails.bankName}`);
console.log(`Account: ${collectionDetails.accountNumber}`);
console.log(`Account name: ${collectionDetails.accountName}`);
console.log(`Transfer exactly ${amountInFiat} ${fiatCurrency}`);
console.log(`Payment window: ${validityPeriod} seconds`);

// Step 2: Verify payment (or use webhooks instead)
const verify = await axios.get(
  `${BASE_URL}/transactions/${reference}/verify`,
);
console.log('Payment status:', verify.data.data.status);

Node.js — CRYPTO

const axios = require('axios');
const { randomUUID } = require('crypto');

const BASE_URL = 'https://api.ivorypay.io/api/v1';
const reference = randomUUID();

// Step 1: Create CRYPTO payment request
const response = await axios.post(
  `${BASE_URL}/transactions`,
  {
    amount: 1000,
    type: 'CRYPTO',
    chain: 'BSC_TESTNET',
    firstName: 'John',
    lastName: 'Doe',
    email: '[e-mail]',
    reference,
    baseFiat: 'NGN',
    mode: 'API',
    crypto: 'USDT',
  },
  {
    headers: { Authorization: process.env.IVORYPAY_SECRET_KEY },
  },
);

const { collectionDetails, amountInCrypto, currency } = response.data.data;
console.log(`Ask customer to send ${amountInCrypto} ${currency} to ${collectionDetails.address}`);

// Step 2: Verify payment (or use webhooks instead)
const verify = await axios.get(
  `${BASE_URL}/transactions/${reference}/verify`,
);
console.log('Payment status:', verify.data.data.status);

cURL — FIAT

BASE_URL="https://api.ivorypay.io/api/v1"

curl -X POST $BASE_URL/transactions \
  -H "Authorization: sk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "email": "[e-mail]",
    "type": "FIAT",
    "mode": "API",
    "baseFiat": "NGN",
    "crypto": "USDT",
    "reference": "ecb1d467-eaa4-4640-ac61-1a777c86f67a"
  }'

cURL — CRYPTO

BASE_URL="https://api.ivorypay.io/api/v1"

curl -X POST $BASE_URL/transactions \
  -H "Authorization: sk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "type": "CRYPTO",
    "chain": "BSC_TESTNET",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[e-mail]",
    "reference": "550e8400-e29b-41d4-a716-446655440000",
    "baseFiat": "NGN",
    "mode": "API",
    "crypto": "USDT"
  }'

# Verify payment status (no auth needed)
curl "$BASE_URL/transactions/550e8400-e29b-41d4-a716-446655440000/verify"