Virtual Accounts Overview

A virtual account is a dedicated Nigerian bank account number tied to one of your customers. Money paid into it credits your NGN balance.

NGN is enabled per account

Ask us to switch it on before you start, or every call below returns a feature-not-enabled error.

Create one

Endpoint

Request Body

reference must be unique to you and acts as the idempotency key. NGN is currently the only supported currency.

The customer must be complete first

This is the most common reason a virtual account request fails, so get it right before you call.

We are required to verify the identity behind every naira account, so the customer record has to carry all of the following before we can issue one:

field	notes
first_name
last_name
email
phone_number
date_of_birth	must be 18 or over
id_type	must be "bvn"
id_number	the 11 digit BVN

The BVN lives on the customer, not on the virtual account request. Set it when you create the customer, or patch an existing one:

Customer

We verify the BVN against the national registry when the account is created. A BVN that does not match the customer's details is rejected.

If anything is missing you get one error naming every missing field at once, so you can fix them in a single pass rather than discovering them one at a time:

Error

Note the error names customer record fields, not fields of the request you just sent. Nothing is wrong with your virtual account payload. Go and update the customer.

Other operations

method	path	purpose
GET	/api/virtual-accounts	List your accounts
GET	/api/virtual-accounts/:id	Fetch one
GET	/api/virtual-accounts/:id/transactions	Deposits into that account
PATCH	/api/virtual-accounts/:id/alias	Change the display name
GET	/api/virtual-accounts/supported-currencies	Currently returns NGN

In sandbox, POST /api/virtual-accounts/:id/simulate-deposit fakes an inbound transfer so you can test without moving real money. It is rejected in production.

Balances

Your existing balance endpoint returns naira alongside your crypto balances. No new call to make.

Naira is reported in major units, so a 1000 balance means one thousand naira.

Errors worth handling

situation	what you get
NGN not enabled for you	feature-not-enabled
Customer missing BVN or other required fields	validation error naming every missing field
BVN does not match the customer's details	verification failure
Amount below ₦500 or above ₦10,000,000	validation error
Order sent without quote_id	validation error
Quote expired or already used	failed precondition
Not enough balance	failed precondition
quantity_in_base_units on an NGN pair	validation error

Common mistakes

Sending kobo. Every naira amount is in whole naira. 5000 is five thousand naira, not fifty.

Reusing a quote. One execution per quote. Get a fresh one for each conversion.

Sitting on a quote. They expire in seconds. Request the quote when you are ready to execute, not at the start of a checkout flow.

Assuming side refers to the pair. It refers to base_currency. If in doubt, put what you are spending in base_currency and use SELL.

Creating a customer without a BVN, then asking for a virtual account. The BVN goes on the customer record via id_type and id_number. Add it up front and you avoid a round trip.