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

# Nigeria

> Rails, beneficiary fields, cut-off times, and failure modes specific to NGN payouts.

## 1. Overview

Nigeria is one of world’s most advanced digital payment markets, but it remains bank-account led, not mobile-money led.

The dominant settlement infrastructure is:

NIP (NIBSS Instant Payments). Fast, interbank settlement rail used across virtually all major Nigerian banks.

Mobile money services like Opay, Palmpay, Moniepoint, and Paga exist, but their infrastructure still mimics the banking model, using account numbers derived from user phone numbers (10 digits).

## 2. Settlement methods available

| Method | Description |
| - | - |
| NIP Instant Bank Transfers | Primary payout rail. Settlement typically within seconds. Covers almost all banks in Nigeria. |
| Digital Wallet Payouts (Opay, Palmpay, Moniepoint, Paga) | Wallet services operating account number systems mapped to phone numbers; treated like bank accounts inside NIP. |

> [!NOTE]
>
> Mobile money in Nigeria is not dominant like in Kenya or Ghana.

Bank accounts dominate digital payments volume and frequency.

## 3. Beneficiary validation standards

Beneficiary detail validation is critical to avoid payout failures. Resolve the account name before paying with [Account Lookup](https://www.bitnob.dev/api-reference/payouts/account-lookup.md), and pull valid institution codes from [Get Banks](https://www.bitnob.dev/api-reference/payouts/banks-by-country.md).

| Type | Validation Process |
| - | - |
| Bank Accounts | 10-digit NUBAN account number + Bank code lookup via NIP Name Enquiry API. |
| Wallet Accounts (Opay, Palmpay, Moniepoint, Paga) | 10-digit wallet account number derived from user's phone number (e.g., 8000000000); validation via same NIP Name Enquiry process, different institution code. |

> [!WARNING]
>
> Always perform a real-time Name Enquiry before allowing the user to proceed with payout confirmation.

## Best practices for name enquiry and validation

Confirm account existence before proceeding.

Display retrieved account name to user for confirmation.

Block payout if retrieved name and user-entered name mismatch substantially

Validate institution codes dynamically (wallets like Opay, Palmpay have their own NIP codes, not bank codes).

## 4. Tiered account structures and impact on payouts

Nigeria’s payment ecosystem uses tiered accounts. The amounts Bitnob will accept for the corridor come from [Get Limits](https://www.bitnob.dev/api-reference/payouts/payout-limits.md):

| Tier Type | Description |
| - | - |
| Tier 1 (Basic Accounts) | Limited KYC; typically ₦50,000 per transaction max, ₦300,000 balance limit. |
| Tier 2 (Medium KYC Accounts) | Higher limits; ₦200,000–₦500,000 transaction limits common. |
| Tier 3 (Fully KYCed Accounts) | Unlimited or very high transaction limits. |

Impact on Payouts:

If a payout exceeds the receiver's allowable **per transaction or maximum balance limit,** the transfer **may be instantly rejected** or **reversed manually by the receiving institution.**

Instant Reversals: Some banks immediately reject and reverse the funds back to the sender.

Product Requirement:

Monitor reversal events actively after payout initiation.

Surface payout pending/reversal status clearly to the user if applicable.

## 5. Payout timing expectations

| Phase | Expected Time |
| - | - |
| Funding Confirmation (Bitcoin/Stablecoin) | \<15 minutes (dependent on network conditions). |
| NIP Payout Processing | Seconds to 5 minutes for most transactions. |
| Beneficiary Account Receipt | Immediate upon successful NIP settlement (seconds typical). |
| Reversal Timing (if applicable) | Instant or within 24 hours depending on receiving institution. |

## 6. Common failure modes

| Failure Mode | Description | Reponse Strategy |
| - | - | - |
| Invalid Account Number | Wrong number format or non-existent account. | Validate during Name Enquiry. Block pre-payout. |
| Name Mismatch | Significant mismatch between user input and retrieved name. | Block or force reconfirmation before proceeding. |
| Tier Limit Exceeded | Payout amount exceeds receiver's account tier limit. | Educate users at payout creation. Monitor for reversals. |
| Receiving Bank Downtime | Rare but possible. Certain banks experience maintenance windows at odd hours. | Monitor NIP switch error codes. Retry if allowed. |
| Payment Timeout (No Response) | NIP response timeout, very rare. | Retry transaction within safe timeout window. |

## 7. Liquidity management considerations

Liquidity in NGN must be actively maintained, especially during political periods where FX volatility can spike.

NGN float should always cover at least 2–3x daily average payout volume.

USD to NGN conversion rates can move dramatically: build volatility buffers inside funding quotes where relevant.

Prefer multiple banking relationships for liquidity redundancy (especially with Tier 1 and Tier 2 banks).

## 8. Operational best practices for Nigeria corridor

| Area | Recommendation |
| - | - |
| Validation | Always validate account number and retrieve name before allowing payout. |
| Error Handling | Track real-time NIP error codes and automate retries where safe. |
| Reversal Monitoring | Integrate webhook or polling systems to detect reversals fast. |
| Tier Awareness | Flag large payouts and advise users to confirm receiver account tier where possible. |
| Payout Splitting | For large payouts, automate splitting if a payout is above the corridor maximum from Get Limits. |
| Downtime Alerts | Monitor known banking maintenance windows (often between midnight and 6am) and notify ops in advance. |

## Quick reference table

| Field | Value |
| - | - |
| Primary Rail | NIP (Instant Bank Transfers) |
| Mobile Wallet Rails | Opay, Palmpay, Moniepoint, Paga (mapped like banks) |
| Standard Account Number Format | 10 digits (bank and wallet accounts) |
| SLA (Normal Conditions) | 98% payouts under 5 minutes |
| Main Risks | Tiered account limits, reversal management, downtime on rare occasions |
| Reversal Timing | Instant (auto) or manual (within 24 hours) |
| Recommended Liquidity Buffer | 2–3x daily payout volume |

Nigeria is a high-volume, fast-paced payout corridor where bank transfers dominate digital transactions.

Building payout systems for Nigeria means:

* Mastering real-time validation,
* Designing for account tier realities,
* Actively monitoring reversals,
* Protecting user trust even during edge-case liquidity or banking downtimes.

A resilient Nigeria payout product is not one that works only under ideal conditions. It is one that anticipates, detects, and recovers from real-world operational stress predictably and transparently.


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