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 account.
  2. Virtual accounts - Created via API by merchants.
  3. Sub-accounts - Created exclusively on Nomba dashboard as a separate pocket of money.
See this guide for more details on managing accounts with Nomba.

​
Create a virtual account

When creating a virtual account, you can optionally include the following fields in your request:
  • bvn: 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: Restricts the account to accept only the specified amount. This is useful for exact payments such as invoice matching or controlled transfers. Any payment above or below the specified value will be rejected.
  • expiryDate: Sets how long the virtual account remains valid.
Be cautious when setting the expectedAmount. Once set, the account will only accept that exact amount. Payments with any other amount will be rejected.
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: