Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.nomba.com/llms.txt

Use this file to discover all available pages before exploring further.

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

At Nomba, virtual accounts are part of the broader Accounts system. A virtual account can be created for a customer primarily to receive payments. Once created, Nomba generates a unique account number that customers can use to receive bank transfers.

​
Types of accounts

Nomba supports the following account types:

​
Primary Accounts

A primary account is automatically created when you set up your business on Nomba.
  • This is your main account.
  • All other accounts (virtual or sub-accounts) are linked to it.

​
Virtual accounts

Virtual accounts are created via API for receiving payments. Funds received are automatically routed to the parent (primary) account.
  • Virtual accounts do not hold balances themselves
  • If required, virtual accounts can be linked to a sub-account instead of the primary account buy adding the subAccountId as a path to the endpoint
  • You can view all virtual account transactions on your dashboard.

​
Sub-accounts

Sub-accounts are created from the Nomba Dashboard
  • They act as separate “pockets” for managing funds
  • Useful for segmenting funds across teams, operations, or workflows.
See this guide for more details on managing accounts with Nomba.

​
Types of Virtual accounts

Nomba supports two types of virtual accounts based on their behavior:

​
Static Virtual Accounts

Static virtual accounts are permanent account numbers assigned to a customer or business. Use a static virtual account when:
  • You do not want the account to expire
  • You want your customers to receive multiple payments over time.
Use cases:
  • Assigning a dedicated account number to a customer
  • Supporting recurring payments
  • When you need a stable, non-expiring account number

​
Dynamic Virtual Accounts

Dynamic virtual accounts are temporary, purpose-specific account numbers.
  • Typically used for one-time or time-bound payments
  • Can be configured with an expiryDate to define validity
  • Dynamic accounts help reduce reconciliation errors for transaction-specific payments.

​
Create a virtual account

We recommend testing virtual account creation in the Sandbox environment before going live.
  • Each user can create a maximum of 2 virtual accounts
  • Each account can receive transfers up to ₦150
  • Transfers can be made from any Nigerian bank.
  • You can update the expected amount (up to ₦150) using the expectedAmount field.
  • All transfers will trigger webhooks to the Sandbox webhook URL.
  • Virtual account expiration is not supported in Sandbox.
To create a virtual account, please take note of the optional and required fields:
  • 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.
If a sender transfers an amount different from the expectedAmount:
  • The transaction may be declined by the sender’s bank, or
  • Automatically reversed, depending on the bank’s handling logic
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: