Skip to main content

Create a virtual account

Generate a unique account number for your customer to receive payment.

Update a virtual account

Update a customer virtual account name and callback URL record.

​
Introduction

In Nomba, creating a virtual account falls under the broader category of Accounts. A virtual account can be created for a customer with the primary purpose of accepting payments. Once created, Nomba will generate a unique account number in which the customer can use to receive inflows. Nomba supports different types of accounts:
  1. Primary accounts - Automatically created when you set up a business on Nomba. This is your main account, and all subsequently created accounts (virtual or sub-accounts) are linked to it.
  2. Virtual accounts - Accounts created via API for receiving payments. Funds received through a virtual account are automatically routed to the parent (primary) account, as virtual accounts do not hold funds themselves. You can still view all virtual-account transactions on your dashboard.
  3. Sub-accounts – Accounts created exclusively from the Nomba Dashboard. They act as separate “pockets” of money that you can use to segment funds for internal operations, teams, or business workflows.
See this guide for more details on managing accounts with Nomba.

​
Types of Virtual accounts

Nomba supports two types of virtual accounts depending on how they behave after creation:

​
Static Virtual Accounts

Static virtual accounts are permanent account numbers assigned to a customer or business.
They do not expire, and can receive multiple payments over time. Use a static virtual account when:
  • You want the customer to have a dedicated account number.
  • You expect recurring deposits.
  • You don’t want the account number to change or expire.

​
Dynamic Virtual Accounts

Dynamic virtual accounts are temporary or purpose-based account numbers typically used for:
  • One-time payments
  • Time-bound transactions
They can be configured with expiryDate to defines when the account becomes invalid Dynamic accounts are ideal for transaction-specific usage and reduce reconciliation errors

​
Create a virtual account

When creating a virtual account, please not that this fields are optional:
  • accountRef (required): A unique reference you assign to the virtual account.
  • accountName (required): The name associated with the virtual account.
  • currency (required): Currency for the virtual account, e.g NGN.
  • bvn (optional): If not provided, the virtual account will inherit the BVN of the parent account. Only include this if you want to assign a different BVN.
  • expectedAmount (optional): Restricts the account to accept only the specified amount. This is useful for exact payments such as invoice matching or controlled transfers. When omitted, the account will accept any amount since it is not restricted to a specific value.
Be cautious when setting the expectedAmount. Once set, the account will only accept that exact amount. Payments with any other amount will be rejected.
  • expiryDate (optional): Sets how long the virtual account remains valid, this is useful if you intend to create a dynamic virtual account purposely for time-based transactions. If omitted, the virtual account functions as a static (permanent) account.
To create a virtual account, send a POST request to this endpoint /v1/accounts/virtual. 
curl --request POST \
  --url https://api.nomba.com/v1/accounts/virtual \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <parent accountId>' \
  --data '{
    "accountRef": "1oWbJQQHLyQ************",
    "accountName": "Daniel Scorsese",
    "currency": "NGN",
    "expiryDate": "2024-06-17 04:55:00",
    "bvn":"12345678901",
    "expectedAmount": 5000.00,
  }'

​
Suspend a virtual account

You cannot suspend a parent account. The parent account is directly tied to your business and always remains active. Only accounts created via the API (i.e., virtual accounts) can be suspended. To suspend a virtual account, send a PUT request with the accountId of the account you want to suspend to /v1/accounts/suspend/{accountId}
Virtual accounts are the only accounts that can be created via API.
curl --request PUT \
  --url https://api.nomba.com/v1/accounts/suspend/{accountId} \
  --header 'Authorization: Bearer <token>' \
  --header 'accountId: <accountid>'

​
Perform a virtual account lookup

You can look up the details of a virtual account using its account number. This is useful for verifying whether an account is still valid, checking expiry status, or retrieving account details before accepting payments. 
curl --request GET \
  --url https://api.nomba.com/v1/accounts/virtual/{virtualAcctNumber} \
  --header 'Authorization: Bearer <token>' \
  --header 'accountId: <accountId>'
What’s Next? After creating a virtual account, there are additional actions you may need to perform: