Create Virtual Accounts

Overview

Virtual accounts are automatically created for your business in each currency where you have been successfully onboarded with a banking provider. You can also create additional virtual accounts by linking them to custom wallets for segregated fund management.

Default Virtual Accounts

When your onboarding is successful, virtual accounts are provisioned for your business in the supported currencies for that provider. These are your primary virtual accounts and are immediately available once active.

You can view your primary virtual accounts by calling the List Virtual Accounts endpoint:

GET /business/virtual-accounts

Creating Additional Virtual Accounts

You can create additional virtual accounts by calling the Create Wallet endpoint and passing createVirtualAccount: true in the request body. This creates a custom wallet with a linked virtual account, useful for segregating funds by client, use case, or business unit.

POST /business/sub-wallets

{
  "name": "Merchant Collection - Acme Corp",
  "sequenceId": "merchant-acme-001",
  "currency": "NGN",
  "createVirtualAccount": true
}

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "partnerId": "9ecf5248-17e7-4a2b-b5a8-3bd58ff0fe01",
  "sequenceId": "merchant-acme-001",
  "name": "Merchant Collection - Acme Corp",
  "currency": "NGN",
  "status": "active",
  "availableBalance": 0,
  "createdAt": "2025-02-10T12:00:00.000Z",
  "updatedAt": "2025-02-10T12:00:00.000Z",
  "virtualAccount": {
    "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "userId": "9ecf5248-17e7-4a2b-b5a8-3bd58ff0fe01",
    "subwalletId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "currency": "NGN",
    "accountNumber": "1122334455",
    "routingNumber": "",
    "accountName": "YC / Acme Corp",
    "bankName": "Bank Name",
    "bankAddress": "",
    "status": "PENDING",
    "createdAt": "2025-02-10T12:00:00.000Z",
    "updatedAt": "2025-02-10T12:00:00.000Z"
  }
}

Account Creation is Asynchronous

Virtual account creation is an asynchronous operation. When a virtual account is created, it starts in PENDING status and transitions to ACTIVE once the banking provider has fully provisioned the account. Webhook notifications are sent for each status change — see the Webhooks page for details.

Account Statuses

You can check the current status of a virtual account at any time by calling the Get Virtual Account by ID endpoint:

GET /business/virtual-accounts/lookup/c3d4e5f6-a7b8-9012-cdef-345678901234

{
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "userId": "9ecf5248-17e7-4a2b-b5a8-3bd58ff0fe01",
  "subwalletId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "currency": "NGN",
  "accountNumber": "1122334455",
  "routingNumber": "",
  "accountName": "YC / Acme Corp",
  "bankName": "Bank Name",
  "bankAddress": "",
  "status": "ACTIVE",
  "createdAt": "2025-02-10T12:00:00.000Z",
  "updatedAt": "2025-02-10T12:01:30.000Z"
}

Receiving Funds

When funds are received into a virtual account, they are processed as receives and credited to the associated balance. Webhook events are sent when funds are received. You can check the status of a receive by calling the Lookup Receive endpoint.

Simulating Deposits (Sandbox Only)

In the sandbox environment, you can simulate a deposit into any of your virtual accounts to test your integration end-to-end without moving real funds. This triggers the same processing pipeline as a real deposit including webhook notifications and balance updates on the associated wallet.

Call the Simulate Deposit endpoint with the target virtual account number and the amount to credit:

POST /business/virtual-accounts/simulate-deposit

{
  "accountNumber": "3183934429",
  "amount": 1000
}

Once the simulated deposit is processed, your configured webhook endpoint will receive the same events as a real deposit, and the receive can be looked up via the Lookup Receive endpoint.

This endpoint is only available in the sandbox environment and will not work against production.