​

Virtual Accounts API Breaking Changes

​

Why This Changed

​

What Changed

​

New Endpoints

​

Pagination Details

​

New Features

• Virtual account labels: Add custom labels to organize accounts (e.g., “Customer A”, “Payroll”)
• Account regeneration: Generate new account numbers with reason tracking for audit purposes
• Transaction history: Query transactions linked to specific virtual accounts

​

Migration Guide

const response = await fetch(`/wallets/${walletId}/virtual-accounts`);
const account = await response.json();

console.log(account.accountNumber);
console.log(account.bankName);

const response = await fetch(`/wallets/${walletId}/virtual-accounts`);
const { data, meta } = await response.json();

// Handle empty array case
if (data.length === 0) {
  console.log('No virtual accounts found');
  return;
}

// Get the first account (equivalent to old behavior)
const account = data[0];
console.log(account.accountNumber);
console.log(account.bankName);

// Or iterate through all accounts
for (const account of data) {
  console.log(account.accountNumber);
}

// Pagination info available in meta
console.log(`Page ${meta.currentPage} of ${meta.totalPages}`);

const response = await fetch(`/wallets/${walletId}/virtual-accounts/${virtualAccountId}`);

if (!response.ok) {
  console.log('Virtual account not found');
  return;
}

const { data } = await response.json();
console.log(data.accountNumber);

​

Example API Response

{
  "message": "Virtual accounts retrieved successfully",
  "statusCode": 200,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "accountNumber": "8012345678",
      "accountName": "Blockradar/John Doe",
      "bankName": "Wema Bank",
      "bankCode": "035",
      "isActive": true,
      "type": "AUTO_FUNDING",
      "label": "Customer Deposits",
      "createdAt": "2026-01-22T10:30:00.000Z",
      "updatedAt": "2026-01-22T10:30:00.000Z"
    }
  ],
  "meta": {
    "itemCount": 1,
    "totalItems": 1,
    "itemsPerPage": 10,
    "totalPages": 1,
    "currentPage": 1
  }
}

{
  "message": "Virtual account retrieved successfully",
  "statusCode": 200,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "accountNumber": "8012345678",
    "accountName": "Blockradar/John Doe",
    "bankName": "Wema Bank",
    "bankCode": "035",
    "isActive": true,
    "type": "AUTO_FUNDING",
    "label": "Customer Deposits",
    "createdAt": "2026-01-22T10:30:00.000Z",
    "updatedAt": "2026-01-22T10:30:00.000Z"
  }
}

​

Need Help?

• Documentation: Virtual Accounts guide
• API Reference: Virtual Accounts endpoints
• Email support: [email protected]

​

Virtual Accounts API

• New feature: Virtual Accounts API enables businesses to create and manage virtual bank accounts linked to master wallets or child addresses
• Fiat-to-stablecoin conversion: Customers can receive NGN payments through traditional bank transfers, automatically converted to cNGN stablecoins
• Auto-funding support: AUTO_FUNDING type accounts automatically mint cNGN when fiat payments are received and transfer to linked wallets
• Master wallet integration: Create virtual accounts directly linked to master wallets
• Child address integration: Create virtual accounts linked to specific child addresses for granular control
• Account management: Activate or deactivate virtual accounts to control auto-funding behavior

​

What you need to do

• Enable the feature: Contact [email protected] to enable virtual accounts for your business
• Ensure cNGN support: Make sure your master wallet supports the cNGN stablecoin asset
• Mainnet only: Note that virtual accounts are only available in the MAINNET environment
• Review API endpoints: Check the Virtual Accounts API documentation for implementation details

​

API Endpoints

​

Master Wallet Endpoints

• POST /wallets//virtual-accounts – Create a virtual account for a master wallet
• GET /wallets//virtual-accounts – Retrieve virtual account details
• PATCH /wallets//virtual-accounts/ – Update virtual account status

​

Child Address Endpoints

• POST /wallets//addresses//virtual-accounts – Create a virtual account for a child address
• GET /wallets//addresses//virtual-accounts – Retrieve virtual account details
• PATCH /wallets//addresses//virtual-accounts/ – Update virtual account status

​

Key Features

• Supported currency: NGN (Nigerian Naira) for fiat payments, cNGN for stablecoin conversion
• Auto-funding flow: Automatic minting and transfer of cNGN when payments are received (AUTO_FUNDING type)
• Account activation: Control auto-funding behavior by activating or deactivating accounts
• Customer management: Create accounts with customer information (firstname, lastname, email, phone)

​

cNGN Testnet Address Updates

• Updated cNGN testnet addresses: The cNGN team has updated their testnet addresses across multiple networks
• New asset support: Added support for the updated cNGN stablecoin in the dashboard
• Asset management: Previous testnet addresses are now labeled as “old” and will be removed in 30 days
• Tron USDT support: Added updated supported Tron USDT address with previous address labeled as “old”

​

What you need to do

• Go to your dashboard and add the new cNGN assets (look for the ones without the “old” label)
• Update your integrations to use the new testnet addresses
• The old testnet addresses will be automatically removed after 30 days
• Note: These changes only apply to testnet environments - mainnet addresses remain unchanged

​

Updated Testnet Addresses

​

Updated Tron USDT Address