Create virtual account

You can use this endpoint to create a virtual account to receive payments.

POST /v1/accounts/virtual

Create virtual account

cURL

curl --request POST \
  --url https://api.nomba.com/v1/accounts/virtual \
  --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,
  "callbackUrl": "https://merchant.example.com/webhooks/nomba"
}
'

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. Both methods return an access token. Send it in the Authorization header: Authorization: Bearer <access_token>.

Headers

accountId · string<uuid> · required

The parent accountId of the business.

Example:

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

Body

application/json

The request payload required to create an 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

callbackUrl · string<uri>

URL to receive payment_success and payment_failed webhook events for inflows into this virtual account. Optional.

Example:

"https://merchant.example.com/webhooks/nomba"

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