> ## 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 API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# Validate a beneficiary

> Beneficiary details are the leading cause of failed payouts. Resolve the destination country's requirements, bank codes, and account name before you initialize.

The local bank or mobile money operator is the first party that validates an account number, and by then your payout is already in flight. Failed delivery is the most common payout failure, and every case of it is avoidable with three lookups before you initialize.

This guide assumes you can already make signed requests; see [Authentication](https://www.bitnob.dev/api-reference/authentication/authentication.md) if not.

**1. Confirm the destination is supported**

```http theme={null}
GET {BASE_URL}/api/payouts/supported-countries
```

[Supported countries](https://www.bitnob.dev/api-reference/payouts/supported-countries.md) returns the live country and channel matrix for your account. Read it at runtime rather than hardcoding: corridors are added and paused without notice.

Then fetch the exact beneficiary fields the country needs:

```http theme={null}
GET {BASE_URL}/api/payouts/supported-countries/NG
```

[Country requirements](https://www.bitnob.dev/api-reference/payouts/country-requirements.md) returns the corridor's `destination_types` and, for each one, the field schema your `beneficiary` object must match. This is the authoritative source, including the per-country quirks like Australia's `bsb_number` or India's `IFSCode` documented in [Send a SWIFT payout](https://www.bitnob.dev/docs/payouts/swift-payout.md).

**2. Get valid institution codes**

```http theme={null}
GET {BASE_URL}/api/payouts/banks/NG
```

[Banks by country](https://www.bitnob.dev/api-reference/payouts/banks-by-country.md) returns bank names and codes for bank destinations. Mobile money providers aren't in this list: read the `network` options from the country requirements instead. Never let users type a bank code by hand; present this list.

Check the corridor's limits while you are here, so you can reject an out-of-range amount before quoting:

```http theme={null}
GET {BASE_URL}/api/payouts/limits?country=NG&currency=NGN
```

**3. Resolve the account**

[Account lookup](https://www.bitnob.dev/api-reference/payouts/account-lookup.md) confirms the account exists and returns the name it resolves to.

```http theme={null}
# Bank account, Nigeria
GET {BASE_URL}/api/payouts/account-lookup?country=NG&account_number=0123456789&bank_code=000013

# Mobile money, Ghana (MTN)
GET {BASE_URL}/api/payouts/account-lookup?country=GH&type=mobile_money&bank_code=MTN&account_number=233200000000
```

For mobile money, pass `type=mobile_money`, use the provider as `bank_code`, and give the phone number in international format as `account_number`.

```json theme={null}
{
  "success": true,
  "message": "Beneficiary lookup completed",
  "data": {
    "account_name": "JANE DOE",
    "account_number": "233200000000",
    "bank_code": "",
    "bank_name": "",
    "country": "GH",
    "is_verified": true
  }
}
```

Proceed only when `is_verified` is `true`, and show `account_name` to whoever is entering the details so they can confirm it is the person they mean. Mobile money lookups may return `bank_code` and `bank_name` empty; that is normal.

> [!WARNING]
>
> Account lookup doesn't support Ghana bank accounts yet. A lookup with a Ghana bank code returns `400` `VALIDATION_ERROR`. For GHS bank payouts, skip the lookup, take the `bank_code` from Get banks, and have your user confirm the account number and name before you finalize. See [Ghana](https://www.bitnob.dev/docs/payouts/corridor-specific-behavior/ghana-payout.md).

## What this prevents

| Skipped check | What goes wrong |
| - | - |
| Country requirements | Initialize is rejected with `VALIDATION_ERROR`, or worse, accepted with fields the rail later refuses. |
| Bank list | A stale or mistyped bank code fails at the rail, after funding. |
| Account lookup | The payout reaches `PROCESSING`, then fails at delivery, the slowest and most expensive place to fail. |
| Limits | The quote is rejected with `VALIDATION_ERROR`, naming the minimum or maximum, after the user has already committed to an amount in your UI. |

Once the beneficiary resolves, continue with [Send your first payout](https://www.bitnob.dev/docs/payouts/send-your-first-payout.md) or go straight to [Create quote](https://www.bitnob.dev/api-reference/payouts/create-quote.md).


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