Static Virtual Account

Use these endpoints to create and list static virtual bank accounts for your customers. Each static virtual account is a dedicated NGN bank account number that your customer can fund by direct bank transfer — deposits are automatically reconciled against your wallet.

Base path: /v1/virtual-accounts Authentication: Secret key (Authorization: sk_...)

---

Endpoints

Method	Path	Auth	Description
POST	/v1/virtual-accounts/static	API Key	Generate a static virtual account for a customer
GET	/v1/virtual-accounts/static	API Key	List all virtual accounts for your business

---

POST /v1/virtual-accounts/static

Creates a permanent (static) virtual bank account linked to a specific customer. If the customer does not exist yet (looked up by email), one is created automatically.

The account number returned is unique to the customer and can be used indefinitely — any transfer to it is automatically credited to the matched business wallet.

Request Body

Field	Type	Required	Description
email	string	Yes	Customer's email address. Used to resolve or create the customer record.
accountName	string	Yes	Name to assign to the virtual account.
type	string	Yes	Account type. business or individual.
identityType	string	Yes	Identity verification type. cac for business; bvn or nin for individual.
identityNumber	string	Yes	The actual identity number. For business accounts (cac), must begin with RC or BN (e.g. RC1234567). For individual accounts, provide the BVN or NIN digits.
reference	string (UUID)	Yes	A unique UUID you generate to identify this account request.
currency	string	Yes	Currency for the account. Currently only NGN is supported.

Identity type rules

type	Valid identityType values	identityNumber format
business	cac	Must start with RC or BN (e.g. RC1234567)
individual	bvn, nin	Numeric digits only

Request

POST /v1/virtual-accounts/static
Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "email": "[e-mail]",
  "accountName": "Emeka Okafor",
  "type": "individual",
  "identityType": "bvn",
  "identityNumber": "12345678901",
  "reference": "a3f5c1d2-89ab-4c12-b456-426614174000",
  "currency": "NGN"
}

Success Response — 200 OK

{
  "success": true,
  "message": "Static Virtual Account successfully generated",
  "data": {
    "accountName": "Emeka Okafor",
    "accountNumber": "0123456789",
    "bank": "Palmpay",
    "currency": "NGN",
    "reference": "a3f5c1d2-89ab-4c12-b456-426614174000"
  }
}

Response Fields

Field	Type	Description
accountName	string	Name on the virtual account.
accountNumber	string	The virtual bank account number.
bank	string	Bank name where the account is held.
currency	string	Account currency (NGN).
reference	string	The reference you supplied in the request.

Error Responses

Status	Reason
400	Validation failure (missing field, invalid enum, non-UUID reference).
400	The downstream payment provider rejected the identity verification.
401	Missing or invalid API key.

---

GET /v1/virtual-accounts/static

Returns a paginated list of all static virtual accounts created by the authenticated business in the current environment (TEST or LIVE).

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number. Defaults to 1.
limit	number	No	Results per page. Defaults to 10.

Request

GET /v1/virtual-accounts/static?page=1&limit=20
Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Success Response — 200 OK

{
  "success": true,
  "message": "Virtual accounts retrieved successfully",
  "data": {
    "records": [
      {
        "id": "uuid",
        "customerId": "uuid",
        "businessId": "uuid",
        "accountName": "Emeka Okafor",
        "bankName": "Wema Bank",
        "currency": "NGN",
        "accountNumber": "0123456789",
        "reference": "a3f5c1d2-89ab-4c12-b456-426614174000",
        "context": "LIVE",
        "createdAt": "2026-05-14T10:00:00.000Z",
        "updatedAt": "2026-05-14T10:00:00.000Z"
      }
    ],
    "count": 1
  }
}

Error Responses

Status	Reason
401	Missing or invalid API key.

---

Code Examples

Node.js

const axios = require('axios');

// Individual account
const individualResponse = await axios.post(
  'https://api.ivorypay.io/v1/virtual-accounts/static',
  {
    email: '[e-mail]',
    accountName: 'Emeka Okafor',
    type: 'individual',
    identityType: 'bvn',
    identityNumber: '12345678901',
    reference: crypto.randomUUID(),
    currency: 'NGN',
  },
  {
    headers: {
      Authorization: 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
  },
);

// Business account
const businessResponse = await axios.post(
  'https://api.ivorypay.io/v1/virtual-accounts/static',
  {
    email: '[e-mail]',
    accountName: 'Acme Nigeria Ltd',
    type: 'business',
    identityType: 'cac',
    identityNumber: 'RC1234567',
    reference: crypto.randomUUID(),
    currency: 'NGN',
  },
  {
    headers: {
      Authorization: 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
  },
);

console.log(businessResponse.data.data);
// { accountName, accountNumber, bank, currency, reference }

cURL

# Individual account
curl -X POST https://api.ivorypay.io/v1/virtual-accounts/static \
  -H "Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "accountName": "Emeka Okafor",
    "type": "individual",
    "identityType": "bvn",
    "identityNumber": "12345678901",
    "reference": "a3f5c1d2-89ab-4c12-b456-426614174000",
    "currency": "NGN"
  }'

# Business account
curl -X POST https://api.ivorypay.io/v1/virtual-accounts/static \
  -H "Authorization: sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "accountName": "Acme Nigeria Ltd",
    "type": "business",
    "identityType": "cac",
    "identityNumber": "RC1234567",
    "reference": "b7e2d4f1-12cd-4a56-c789-537725285111",
    "currency": "NGN"
  }'

Python

import requests
import uuid

# Individual account
individual_response = requests.post(
    'https://api.ivorypay.io/v1/virtual-accounts/static',
    headers={
        'Authorization': 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type': 'application/json',
    },
    json={
        'email': '[e-mail]',
        'accountName': 'Emeka Okafor',
        'type': 'individual',
        'identityType': 'bvn',
        'identityNumber': '12345678901',
        'reference': str(uuid.uuid4()),
        'currency': 'NGN',
    },
)

# Business account
business_response = requests.post(
    'https://api.ivorypay.io/v1/virtual-accounts/static',
    headers={
        'Authorization': 'sk_live_xxxxxxxxxxxxxxxxxxxxxxxx',
        'Content-Type': 'application/json',
    },
    json={
        'email': '[e-mail]',
        'accountName': 'Acme Nigeria Ltd',
        'type': 'business',
        'identityType': 'cac',
        'identityNumber': 'RC1234567',
        'reference': str(uuid.uuid4()),
        'currency': 'NGN',
    },
)

data = business_response.json()['data']
print(data['accountNumber'], data['bank'])

---

How deposits are processed

1. You generate a virtual account and share accountNumber + bank with your customer.

2. The customer sends a bank transfer to that account number.

3. The bank notifies Ivorypay via webhook.

4. Ivorypay matches the accountNumber to the customer's business, converts the NGN amount to USDT at the live rate, and credits the business wallet.

5. Your webhook endpoint receives a TRANSACTION_UPDATED event with the settled amount.

The deposit reconciliation happens asynchronously — your webhook (configured in the dashboard) will be notified when the credit lands.