Create virtual account for a sub account

You can use this endpoint to create a virtual account to receive payments for a sub account. Funds sent to the virtual account is collected in the sub account specified

POST /v1/accounts/virtual/{subAccountId}

Create virtual account for a sub account

cURL

curl --request POST \
  --url https://api.nomba.com/v1/accounts/virtual/{subAccountId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountid>' \
  --data '
{
  "accountRef": "1oWbJQQHLyQqqf1SwxjSpudeA21",
  "accountName": "Daniel Scorsese",
  "bvn": "12345678",
  "nin": "12345678901",
  "expiryDate": "2026-01-30 12:15:00",
  "expectedAmount": "200.00",
  "restrictInflowToAccountName": true
}
'

200

{
  "code": "00",
  "description": "Success",
  "data": {
    "createdAt": "2023-09-04T07:09:06.900Z",
    "accountHolderId": "01a10aeb-d989-460a-bbde-9842f2b4320f",
    "accountRef": "1oWbJQQHLyQqqf1SwxjSpudeA21",
    "bvn": "12234412345",
    "accountName": "Daniel Scorsese",
    "currency": "NGN",
    "identifierType": "BVN",
    "bankName": "Nombank MFB",
    "bankAccountNumber": "9391076543",
    "bankAccountName": "Nomba/Ifeoluwa Adeboye",
    "callbackUrl": "https://webhook.site/98ef100f-5adc-4434-800a-0808h60bd8d7",
    "expired": true,
    "restrictInflowToAccountName": true
  }
}

For a complete guide on response codes and transaction statuses, see Response Codes.

Authorizations

Authorization · string · header · required

Nomba authenticates API calls with OAuth2 HTTP bearer tokens. There are two methods of authentication; Client-Credentials method and PKCE (Proof Key for Code Exchange) method. In each of the methods, You will get an ACCESS_TOKEN. You need to use an "Authorization" HTTP header to provide your ACCESS_TOKEN. For example: Authorization: {ACCESS_TOKEN}.

Headers

accountId · string<uuid> · required

The parent accountId of the business.

Example:

"890022ce-bae0-45c1-9b9d-ee7872e6ca27"

Path Parameters

subAccountId · string · required

The sub accountId of the business.

Body

application/json

The request payload required to create a virtual account

accountRef · string · required

Account reference

Required string length: 16 - 64

Example:

"1oWbJQQHLyQqqf1SwxjSpudeA21"

accountName · string · required

Account holder's name

Required string length: 8 - 64

Example:

"Daniel Scorsese"

bvn · string

Account holder's BVN. Optional.

Example:

"12345678"

nin · string

Account holder's National Identification Number (NIN). Optional. Must be exactly 11 digits. Can be sent on its own or alongside bvn. If neither is sent, the BVN on the parent business account is used.

Required string length: 11

Pattern: ^\d{11}$

Example:

"12345678901"

expiryDate · string

Account expiry date in UTC. Optional. ⚠️Be careful with this.

Example:

"2026-01-30 12:15:00"

expectedAmount · number<double>

Amount the account can receive. Optional.

Example:

"200.00"

restrictInflowToAccountName · boolean

When set to true, Nomba will reject any inflow to the virtual account whose sender name does not match the virtual account name. The order of names does not matter—for example, a VA name of 'John Doe Naomi' would match sender names like 'Doe John Naomi' or 'Naomi Doe John', since different banks may arrange names differently. A payment_failed webhook event is sent to notify the merchant that the inflow was rejected. The rejected inflow is reversed back to the sender according to the sending bank's policy. Optional.

Example:

true

Response

200

application/json

Virtual account creation successful.

code · string · required

Response Code

Example:

"00"

description · string · required

Response description

Example:

"Success"

data · object · required

Show child attributes