Skip to main content
This guide takes one customer from nothing to a working naira account number. For what virtual accounts are and how deposits are credited, start with the overview. Before you start, make sure virtual accounts are enabled on your account. The Bitnob team switches them on after your KYB review; until then, calls in production are rejected.

​
Issue a virtual account

1

Make sure the customer can pass verification

Nigerian regulation requires identity verification behind every naira account. The customer record must carry first_name, last_name, email, phone_number (a Nigerian mobile number), date_of_birth (18 or over), id_type: "bvn", and the 11-digit BVN as id_number.
The BVN lives on the customer, not on the virtual account request; add it at creation or patch an existing customer.
Customers are matched on email, phone_number and BVN (id_number). If you send an email, phone number or BVN that already belongs to one of your customers, you get 201 Created with that existing customer, and the other fields you sent are ignored. Compare the returned email, phone number and name with what you sent. If they differ, one of those details is already in use, and the virtual account would be issued against the existing customer’s details.
The name and date of birth must exactly match what is registered against the BVN in the national registry. If either differs, verification fails even when the BVN itself is valid.
2

Create the account

Full schema: Create virtual account.
reference is your idempotency key: sending the same reference again returns the existing account, even if you change bank. account_alias is an optional label for your own records. NGN is currently the only supported currency. The response returns the account number the customer can pay into.bank chooses the issuing bank: nomba (Nombank MFB) or globus (Globus Bank). It isn’t case-sensitive. Leave it out and the account opens at the default bank, currently Nomba. bank_name on the response names the bank, but in sandbox it’s always Sandbox Bank, whichever you choose.A customer can hold as many accounts as you need, including one at each bank. Send a new reference for each.
3

Test it in sandbox

POST /api/virtual-accounts/:id/simulate-deposit fakes an inbound transfer so you can exercise the crediting flow without real money. The request body is optional and takes only idempotency_key. Each call credits a fixed ₦10,000 to your company NGN balance, up to ₦100,000 per hour, and fires virtual_account.deposit.success, exactly as a real transfer would. It is rejected in production.

​
Business customers

To open an account for a company, set customer_type to business and add the company’s details to the customer: The personal fields (first_name, last_name, date_of_birth, email, phone_number, dial_code, id_type, and id_number) are those of a director or authorized representative, and follow the same rules as for an individual. The account is created with account_type: "business".

​
Working with issued accounts

​
When something fails

Virtual accounts aren’t enabled on your account yet. They’re switched on after KYB review; contact Bitnob before retrying anything.
The customer record is incomplete. The error lists every missing field at once, for example customer <id> is missing bvn, date_of_birth, so fix them in one pass. It refers to the customer record, not the request you just sent; update the customer and retry.
bank was set to something other than nomba or globus. The request fails with 400 VALIDATION_ERROR. Leave bank out to use the default bank.
The BVN did not match the customer’s registered name or date of birth. Correct the customer record to match the registry.