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	Use API for programmatic integrations.
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 only	Required when type is CRYPTO. The blockchain network. See chains.
reference	string	Yes	A UUID you supply for idempotency and reconciliation.
metadata	string	No	Any JSON string stored on the transaction. Returned as-is in webhooks.

chain is not required for FIAT payments and will be ignored if provided.

---

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

---

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.

---

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   (wrong amount sent)
                                  ↘ 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 a different amount than expected
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.

---

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"