NOnomba
Virtual Accounts

Create virtual account

Changed on

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

post/v1/accounts/virtual

Request

  • Base URL
    https://api.nomba.com
  • URL
    https://api.nomba.com/v1/accounts/virtual
  • Auth
    HTTP bearer

Headers

accountIdstring uuid required
Example:890022ce-bae0-45c1-9b9d-ee7872e6ca27

The parent accountId of the business.

Request body

accountRefstring required

Account reference

accountNamestring required

Account holder's name

bvnstring

Account holder's BVN. Optional.

ninstring

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.

expiryDatestring

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

expectedAmountnumber double

Amount the account can receive. Optional.

restrictInflowToAccountNameboolean

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.

callbackUrlstring uri

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

Example request

{
  "accountRef": "1oWbJQQHLyQqqf1SwxjSpudeA21",
  "accountName": "Daniel Scorsese",
  "bvn": "12345678",
  "nin": "12345678901",
  "expiryDate": "2026-01-30 12:15:00",
  "restrictInflowToAccountName": true,
  "callbackUrl": "https://merchant.example.com/webhooks/nomba"
}

Response

Virtual account creation successful.

codestring required

Response Code

descriptionstring required

Response description

Example response

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

Changes

  • 278a25dccfe5Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status