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

# Virtual account and collection webhooks

> The virtual_account.deposit.success and virtual_account.collection.failed events: when they fire, what each field means, and how to credit a customer exactly once.

Money arriving in a virtual account isn't something you can read from an API response, so Bitnob tells you with a webhook. Two events cover NGN virtual accounts and KES and UGX mobile money collections:

| Event | Fires when |
| - | - |
| `virtual_account.deposit.success` | Money lands in an NGN virtual account, or a payer completes a mobile money collection. Your balance has been credited. |
| `virtual_account.collection.failed` | A mobile money collection ends unpaid: it expired, or the payer didn't complete it. |

Every delivery has the same envelope, `{"event_id", "event", "data"}`. Each one is signed: the `X-Bitnob-Signature` header is an HMAC-SHA512 of the raw request body, keyed with your webhook secret. Verification, retries, and source IPs work the same way as every other Bitnob webhook, and are covered on [Webhooks](https://www.bitnob.dev/api-reference/webhooks.md).

## `virtual_account.deposit.success`

Fired when a transfer into one of your NGN virtual accounts is confirmed, normally within 10 minutes of the sender's transfer, or when a payer approves a mobile money collection. The funds credit your company balance in that currency, not a per-customer balance. Use it to mark an order paid, release goods, or credit the customer in your own ledger.

```json virtual_account.deposit.success theme={null}
{
  "event": "virtual_account.deposit.success",
  "event_id": "00000000-0000-0000-0000-000000000003",
  "data": {
    "amount": "5000000",
    "currency": "NGN",
    "transaction_id": "00000000-0000-0000-0000-000000000004",
    "ledger_transaction_id": "00000000-0000-0000-0000-000000000004",
    "provider_transaction_id": "00000000-0000-0000-0000-000000000005",
    "reference": "DEP_000000000000001",
    "virtual_account_id": "00000000-0000-0000-0000-000000000001"
  }
}
```

| Field | Type | Description |
| - | - | - |
| `event` | string | Always `virtual_account.deposit.success` for this event. Route on this value. |
| `event_id` | UUID | Unique per event. Use it as an idempotency key so a redelivered event isn't credited twice. |
| `data.amount` | string | Amount credited, as an integer string in base units: kobo for NGN, cents for KES and UGX. `"5000000"` is ₦50,000.00, and `"150000"` is KES 1,500. |
| `data.currency` | string | `NGN` for a bank virtual account. `KES` or `UGX` for a mobile money collection. |
| `data.virtual_account_id` | UUID | The account or collection the money landed in. Use it to attribute the deposit to a customer or an order. |
| `data.transaction_id` | UUID | The transaction for this deposit. Matches `transaction_id` on [Get account transactions](https://www.bitnob.dev/api-reference/virtual-accounts/get-account-transactions.md). |
| `data.ledger_transaction_id` | UUID | Same value as `transaction_id`. Use `transaction_id` in new integrations. |
| `data.provider_transaction_id` | string | Identifier from the upstream bank or network. Quote it when you raise a query about a specific payment. |
| `data.reference` | string | Reference for the deposit. Matches the transaction returned by [Get account transactions](https://www.bitnob.dev/api-reference/virtual-accounts/get-account-transactions.md). |

> [!NOTE]
>
> Mobile money collections also send `lifetime`, `rail`, and `network` inside `data`.

## `virtual_account.collection.failed`

Fired when a mobile money collection closes without being paid, either because it expired or because the payer didn't complete the payment. Nothing is credited. Use it to mark the order unpaid, or to ask the payer again with a new collection and a new `reference`.

To see why the collection ended, fetch it with [Get virtual account](https://www.bitnob.dev/api-reference/virtual-accounts/get-virtual-account.md). It has `status: "closed"` and `failure_reason` set.

This event is only sent for mobile money collections.

## Handle it once

1. Verify the `X-Bitnob-Signature` header over the raw body. See [Verify every delivery](https://www.bitnob.dev/api-reference/webhooks.md#verify-every-delivery).
2. Skip the event if you've already processed its `event_id`.
3. Route on `event`.
4. For `virtual_account.deposit.success`, look up which customer or order owns `data.virtual_account_id`, and credit `data.amount` in the base units of `data.currency`.
5. Respond `200`. If your own processing fails temporarily, respond with a `5xx` so the event is retried.

Reconcile on a schedule with [Get account transactions](https://www.bitnob.dev/api-reference/virtual-accounts/get-account-transactions.md), so a missed delivery never becomes a missing credit.

## Test it in sandbox

Call [Simulate deposit](https://www.bitnob.dev/api-reference/virtual-accounts/simulate-deposit-sandbox.md) instead of waiting on a real payment. Events go to the webhook URL set in your sandbox dashboard.

* **NGN virtual account:** each call credits a fixed ₦10,000 (`"1000000"` kobo), up to ₦100,000 per hour, and sends `virtual_account.deposit.success`.
* **Mobile money collection:** send `"outcome": "success"` to credit the expected amount and send `virtual_account.deposit.success`, or `"outcome": "failed"` to end it unpaid and send `virtual_account.collection.failed`. See [Collect mobile money](https://www.bitnob.dev/docs/fiat-collections/collect-mobile-money.md#test-in-sandbox).


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