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 The BVN lives on the customer, not on the virtual account request; add it at creation or patch an existing customer.
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.2
Create the account
Full schema: Create virtual account.
reference is your idempotency key: sending the same reference again returns the existing account. account_alias is an optional label for your own records. NGN is the only currency for bank accounts. The response returns the account number the customer can pay into.bank is the issuing bank. Globus Bank (globus) is the only supported bank and the default, so you can leave bank out. The value isn’t case-sensitive. bank_name on the response names the bank, but in sandbox it’s always Sandbox Bank.A customer can hold as many accounts as you need. 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, setcustomer_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
Rejected in production
Rejected in production
Virtual accounts aren’t enabled on your account yet. They’re switched on after KYB review; contact Bitnob before retrying anything.
Validation error naming missing customer fields
Validation error naming missing customer fields
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.Unsupported bank
Unsupported bank
bank was set to a bank that isn’t supported. The request fails with 400 VALIDATION_ERROR. Set bank to globus, or leave it out.Verification failure
Verification failure
The BVN did not match the customer’s registered name or date of birth. Correct the customer record to match the registry.