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

# Fiat collections

> Collect local currency into your company balance: NGN by bank transfer to a virtual account, and KES or UGX by mobile money.

Fiat collections let you receive local currency from your customers and credit it to your company balance. There are two ways to collect:

| | NGN virtual accounts | KES and UGX mobile money |
| - | - | - |
| How the payer pays | Bank transfer to a dedicated account number | Approves a prompt on their phone |
| Lifetime | Permanent: one account per customer, paid into any number of times | One-off: one payment for an exact amount, then it closes |
| Customer record and KYC | Required | Not needed |
| Countries | Nigeria | Kenya (M-Pesa) and Uganda (MTN, Airtel) |

Both use the same API. [Create virtual account](https://www.bitnob.dev/api-reference/virtual-accounts/create-virtual-account.md) opens a bank account by default, or a mobile money collection with `rail: "mobile_money"`, and both report payments through the same [webhooks](https://www.bitnob.dev/docs/fiat-collections/deposit-webhook.md). That's why the API reference lists both under virtual accounts.

## NGN virtual accounts

A virtual account is a dedicated Nigerian bank account number assigned to one of your customers. Anyone can pay into it by ordinary bank transfer. Bitnob identifies the deposit and credits **your company's** [NGN balance](https://www.bitnob.dev/api-reference/balances/list-balances.md), tagged with the account it came through, so you always know which customer paid.

It's the simplest way to receive naira: give each customer their own account number and stop matching transfers to people by hand.

### When to use it

| You are building | Virtual accounts let you |
| - | - |
| A wallet or fintech app | Give every user a personal account number to top up from any Nigerian bank. |
| Invoicing or collections | Issue an account per customer, so every payment arrives already attributed. |
| A crypto on-ramp | Collect naira, then convert it with an [NGN trade](https://www.bitnob.dev/docs/trading/overview.md). |

### How it works

**1. Set up the customer**

Every virtual account belongs to a customer, and Nigerian regulation requires a verified identity behind it. The [customer record](https://www.bitnob.dev/api-reference/customers/create-customer.md) must carry a BVN, date of birth, and contact details.

**2. Issue the account**

One call to [Create virtual account](https://www.bitnob.dev/api-reference/virtual-accounts/create-virtual-account.md) returns the account number and bank name to show your customer. Accounts open at Globus Bank.

**3. Your customer pays in**

The customer sends a bank transfer to the account number. Bitnob credits your NGN balance and tags the deposit with the virtual account.

**4. You track the deposit**

Each deposit fires a [`virtual_account.deposit.success`](https://www.bitnob.dev/docs/fiat-collections/deposit-webhook) webhook. [Get account transactions](https://www.bitnob.dev/api-reference/virtual-accounts/get-account-transactions.md) lists everything an account has received.

### The NGN collection model

| Topic | Detail |
| - | - |
| Currency | NGN only |
| Issuing bank | Globus Bank (`globus`) |
| Where funds land | Your company NGN balance, not a per-customer balance |
| Accounts per customer | As many as you need |
| Collection fee | None |
| Funding limits | No per-deposit, daily, or monthly limit |
| Crediting time | Within 10 minutes of the transfer, barring delays at the sending bank |
| Amounts | Kobo, as an integer string: `"100000"` is ₦1,000.00 |

## Mobile money collections

A collection asks one payer for one payment. You send the amount and the payer's phone number, the payer approves a prompt on their phone, and Bitnob credits your company's KES or UGX balance. The collection then closes.

Collections use the same endpoints as NGN virtual accounts, with `rail: "mobile_money"`. They don't need a customer record or KYC.

| Topic | Detail |
| - | - |
| Currencies and networks | KES on M-Pesa (Kenya). UGX on MTN or Airtel (Uganda). |
| Amount | Set by you. The payer must pay that exact amount. |
| Payments per collection | One. The collection closes once it's paid. |
| Time to pay | About an hour. An unpaid collection then closes on its own. There's no cancel endpoint. |
| Where funds land | Your company KES or UGX balance |
| Amounts | Base units, where 100 is 1 KES or 1 UGX: `150000` is KES 1,500 |
| Outcome | `virtual_account.deposit.success` when paid, `virtual_account.collection.failed` when it ends unpaid |

The full flow, limits and errors are in [Collect KES and UGX by mobile money](https://www.bitnob.dev/docs/fiat-collections/collect-mobile-money.md).

## Getting access

The Bitnob team enables NGN virtual accounts and NGN trading together once your KYB is complete. There's no self-serve toggle, and review usually takes 24 to 48 hours after all your documents are in. Until then, virtual account calls in production are rejected.

Mobile money collections are enabled separately, for each currency. Until they're on, creating a collection returns `403` `FEATURE_NOT_ENABLED`.

## Where to go next

> [card] [Set up virtual accounts](https://www.bitnob.dev/docs/fiat-collections/set-up-virtual-accounts.md)
>
> Prepare the customer, issue the account, and test deposits in sandbox.

> [card] [Collect mobile money](https://www.bitnob.dev/docs/fiat-collections/collect-mobile-money.md)
>
> Prompt a payer in Kenya or Uganda, and test both outcomes in sandbox.

> [card] [Create virtual account](https://www.bitnob.dev/api-reference/virtual-accounts/create-virtual-account.md)
>
> The full request and response schema.

> [card] [Currencies and amounts](https://www.bitnob.dev/docs/getting-started/core-concepts-and-architecture/currencies-and-amounts.md)
>
> Which unit each product uses, including kobo and cents for virtual accounts.

> [card] [Convert naira](https://www.bitnob.dev/docs/trading/overview.md)
>
> Trade collected NGN into USDT, USDC, or BTC.


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