> ## Documentation Index
> Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bitnob has two APIs. The Business API (payouts, cards, trading, virtual accounts, stablecoin and bitcoin transfers) is at https://api.bitnob.com. The Enterprise API (non-custodial wallets) is at https://api.platform.bitnob.com.
> Business API auth: sign every request with HMAC-SHA256 and send four headers: `X-Auth-Client` (your client ID), `X-Auth-Timestamp` (Unix seconds), `X-Auth-Nonce` (16 random bytes, hex), and `X-Auth-Signature`, the hex HMAC-SHA256 of `CLIENT_ID:TIMESTAMP:NONCE:BODY` keyed with your client secret. BODY is the exact request body string you send, or an empty string. A missing header, a bad signature, or a timestamp more than about 5 minutes off returns `401`.
> Enterprise API auth: send your key in the `X-API-Key` header. Write requests such as creating a transaction also need an `Idempotency-Key` header, or they fail with `idempotency_key_required` before anything happens.
> Sandbox and production share the Business API base URL. The credentials you sign with select the environment, and `GET /api/whoami` returns it in `data.environment`. Use sandbox credentials in sample code and tests, and never put live credentials in code.
> Amounts are strings unless stated otherwise. Never parse them into floats. Balances, transactions, withdrawals (`POST /api/withdrawals`) and virtual accounts use integer strings in the smallest unit: satoshis for BTC, 6 decimals for USDT and USDC, kobo for NGN, and cents for KES and UGX (100 is 1 KES or 1 UGX). A mobile money collection takes `amount` as a JSON integer in cents.
> Payouts and trading use decimal strings in major units: a payout quote `amount` of `"1"` is 1 USDT, and a trading `quantity` of `"0.0001"` is 0.0001 BTC. Payout responses also carry `cent_amount`, the settlement amount in minor units.
> Card amounts are micro-units (1 USD = 1,000,000). Send them as JSON integers. Card responses return them as integer strings, and card webhooks as integers.
> Generate a unique `reference` for each money movement before the first attempt, and reuse it on retries. A reused reference returns `409` on payout quotes (`ALREADY_EXISTS`), withdrawals (`DUPLICATE_KEY_ERROR`) and card creation (`ALREADY_EXISTS`). It returns the existing record on NGN-pair trading orders, NGN virtual accounts and active mobile money collections. On a mobile money collection that has closed or failed it returns `409` `DUPLICATE_REFERENCE`. It isn't checked on crypto-pair trading orders, so look the order up with `GET /api/trading/orders/{reference}` before resending.
> Quotes expire at `expires_at`; read it from the response instead of assuming a window. An expired trading quote returns `422` `PRECONDITION_FAILED`, and an expired payout quote returns `400` `VALIDATION_ERROR`. Create a new quote rather than retrying. A payout quote can be initialized once, and a trading quote is consumed by the order that fills it.
> Webhooks: verify the `x-bitnob-signature` header, the hex HMAC-SHA512 of the raw request body keyed with your webhook secret, before parsing JSON. Compare in constant time and de-duplicate on `event_id`. A successful API response means accepted: confirm the outcome from the webhook, such as `payouts.withdrawal.success`.
> Errors return `status`, `code` and `detail`. Branch on `code`, never on `detail`. Since the November 5, 2026 response format change, each company gets either the current or the new error codes until its cutoff date, so handle both: `PROVIDER_ERROR` or `PROCESSING_ERROR`, and `BVN_PROVIDER_UNAVAILABLE` or `BVN_VERIFICATION_UNAVAILABLE`. A body that fails to parse returns `{"error": {"code": "BAD_REQUEST"}}`.

# Set up NGN virtual accounts

> Prepare a BVN-verified customer, issue their virtual account, test deposits in sandbox, and handle the errors on the way.

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](https://www.bitnob.dev/docs/fiat-collections/overview.md). To collect KES or UGX by mobile money instead, see [Collect mobile money](https://www.bitnob.dev/docs/fiat-collections/collect-mobile-money.md).

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](https://www.bitnob.dev/api-reference/customers/create-customer.md) 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`.

```json theme={null}
{
  "email": "jane.doe@example.com",
  "customer_type": "individual",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1994-03-21",
  "phone_number": "8000000003",
  "dial_code": "+234",
  "id_type": "bvn",
  "id_number": "12345678901",
  "country": "NGA"
}
```

The BVN lives on the customer, not on the virtual account request; add it at creation or [patch an existing customer](https://www.bitnob.dev/api-reference/customers/update-customer.md).

> [!WARNING]
>
> 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.

> [!WARNING]
>
> 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](https://www.bitnob.dev/api-reference/virtual-accounts/create-virtual-account.md).

```http theme={null}
POST /api/virtual-accounts
```

```json theme={null}
{
  "reference": "your-unique-reference",
  "currency": "NGN",
  "customer_id": "<customer uuid>",
  "account_alias": "Optional internal label",
  "bank": "globus"
}
```

`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`](https://www.bitnob.dev/api-reference/virtual-accounts/simulate-deposit-sandbox) 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`](https://www.bitnob.dev/docs/fiat-collections/deposit-webhook), 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:

| Field | Notes |
| - | - |
| `company_name` | The company's registered name |
| `registration_number` | For example `RC0000000` |

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"`.

```json theme={null}
{
  "customer_type": "business",
  "company_name": "Doe Foods Ltd",
  "registration_number": "RC0000000",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-04-12",
  "id_type": "bvn",
  "id_number": "22200000000",
  "email": "john.doe@example.com",
  "phone_number": "8000000003",
  "dial_code": "+234",
  "country": "NGA"
}
```

## Working with issued accounts

| Method | Path | Purpose |
| - | - | - |
| GET | `/api/virtual-accounts` | List your accounts. Filter with `rail=bank` to leave out mobile money collections. |
| GET | `/api/virtual-accounts/:id` | Fetch one |
| GET | `/api/virtual-accounts/:id/transactions` | Deposits into that account |
| PATCH | `/api/virtual-accounts/:id/alias` | Change your internal label. Payers don't see it. |
| GET | `/api/virtual-accounts/supported-currencies` | Returns NGN on the bank rail, and KES and UGX on the mobile money rail with their networks and limits |

## When something fails

> [accordion] Rejected in production
>
> Virtual accounts aren't enabled on your account yet. They're switched on after KYB review; contact Bitnob before retrying anything.

> [accordion] 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.

> [accordion] 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.

> [accordion] Verification failure
>
> The BVN did not match the customer's registered name or date of birth. Correct the customer record to match the registry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.