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

# Name check and institutions

> List the banks and mobile money operators you can pay, and look up the name on an account before you pay it.

A name check asks the bank or operator who owns an account. Run it before the first payout to any new recipient and show the name to your user.

> [!WARNING]
>
> A payout to a real account that belongs to the wrong person is not something Payve can reverse.
> The name check is your chance to catch a mistyped account number.

Two endpoints cover everything on this page:

| You want to | Call |
| - | - |
| List banks, mobile money operators, or both | `GET /v1/payouts/institutions` |
| Check a bank account or a mobile number | `GET /v1/payouts/validate-account` |

## List institutions

`GET /v1/payouts/institutions?country=NG&type=bank`

**country** `string` (default: NG)

Two-letter country code: `NG`, `GH` or `KE`.

**type** `string`

`bank` or `mobile_money`. Leave it out to get both in one list.

```bash Banks
curl "$PAYVE_API_URL/v1/payouts/institutions?country=NG&type=bank" \
  -H "x-api-key: $PAYVE_API_KEY"
```

```bash Mobile money operators
curl "$PAYVE_API_URL/v1/payouts/institutions?country=GH&type=mobile_money" \
  -H "x-api-key: $PAYVE_API_KEY"
```

```bash Both
curl "$PAYVE_API_URL/v1/payouts/institutions?country=GH" \
  -H "x-api-key: $PAYVE_API_KEY"
```

Every item carries a `type`, so you can tell the two kinds apart in one list.

> [tab] A bank
>
> ```json
> {
>   "data": [
>     {
>       "id": 14,
>       "country": "NG",
>       "name": "Guaranty Trust Bank",
>       "shortName": "GTBank",
>       "bankCode": "058",
>       "swiftCode": null,
>       "bic": null,
>       "branchCode": null,
>       "capabilities": [],
>       "enabled": true,
>       "metadata": null,
>       "type": "bank"
>     }
>   ]
> }
> ```
>
> Use `bankCode` in a name check and in a payout.

> [tab] A mobile money operator
>
> ```json
> {
>   "data": [
>     {
>       "id": 3,
>       "country": "GH",
>       "name": "MTN",
>       "prefixes": ["024", "054", "055", "059"],
>       "enabled": true,
>       "type": "mobile_money"
>     }
>   ]
> }
> ```
>
> `prefixes` lists the number prefixes that belong to the operator. Use `name` as the `operator` in a name check.

> [!NOTE]
>
> Nigeria has no mobile money operators in this list. Payouts to Nigeria go to bank accounts only.

> [!TIP]
>
> Cache the list for a few hours. Do not hard-code bank codes: fetch them, so new banks appear
> without a release.

## Check an account

`GET /v1/payouts/validate-account`

**type** `string` *required*

`bank` or `mobile_money`.

**country** `string` (default: NG)

Two-letter country code.

**accountNumber** `string`

The bank account number. Required when `type` is `bank`.

**bankCode** `string`

The bank's code from the institutions list. Required when `type` is `bank`.

**mobileNumber** `string`

The mobile money number. Required when `type` is `mobile_money`.

**operator** `string`

The operator's name from the institutions list. Required when `type` is `mobile_money`.

A request that leaves out a field its `type` needs is refused with `422`.

> [tab] Bank account
>
> ```bash cURL
> curl "$PAYVE_API_URL/v1/payouts/validate-account?type=bank&bankCode=058&accountNumber=0123456789&country=NG" \
>   -H "x-api-key: $PAYVE_API_KEY"
> ```
>
> ```javascript Node
> const params = new URLSearchParams({
>   type: 'bank',
>   bankCode: '058',
>   accountNumber: '0123456789',
>   country: 'NG',
> });
> const res = await fetch(`${process.env.PAYVE_API_URL}/v1/payouts/validate-account?${params}`, {
>   headers: { 'x-api-key': process.env.PAYVE_API_KEY },
> });
> const { data } = await res.json();
> // Show data.accountName to your user and ask them to confirm.
> ```
>
> ```python Python
> import os, requests
>
> res = requests.get(
>     f"{os.environ['PAYVE_API_URL']}/v1/payouts/validate-account",
>     headers={"x-api-key": os.environ["PAYVE_API_KEY"]},
>     params={"type": "bank", "bankCode": "058", "accountNumber": "0123456789", "country": "NG"},
> )
> data = res.json()["data"]
> # Show data["accountName"] to your user and ask them to confirm.
> ```
>
> ```json Response · 200
> {
>   "data": {
>     "accountName": "Ngozi Adeyemi",
>     "accountNumber": "0123456789"
>   }
> }
> ```
>
> `accountName` can be `null` when the bank returns no name. Treat that as "not confirmed", not as a pass.
>
> A Nigerian account number must be exactly 10 digits. Anything else returns `422 validation_invalid_beneficiary` without asking the bank.

> [tab] Mobile money number
>
> ```bash cURL
> curl "$PAYVE_API_URL/v1/payouts/validate-account?type=mobile_money&mobileNumber=233241234567&operator=MTN&country=GH" \
>   -H "x-api-key: $PAYVE_API_KEY"
> ```
>
> ```json Response · 200
> {
>   "data": {
>     "valid": true,
>     "accountName": null,
>     "mobileNumber": "233241234567"
>   }
> }
> ```
>
> `valid` is `false` when the number is not between 9 and 15 digits. `accountName` is the subscriber's name when the operator returns one, and is often `null`.
>
> > [!WARNING]
> >
> > `valid: true` with `accountName: null` confirms only that the number is well-formed. It does
> > not confirm who owns the wallet. Have your user double-check the number.

## Use the result

**1. Show the name**

Display `accountName` exactly as returned.

**2. Ask your user to confirm**

Let them say "yes, that is who I am paying" before you create the payout.

**3. Send the payout**

Put the confirmed name in `beneficiary.holderName`.

> [!TIP]
>
> Do not auto-reject on a name that differs slightly from what your user typed. Banks abbreviate,
> reorder and truncate names. Show the bank's version and let a person decide.

## In the sandbox

Name checks return made-up names. The same account number always returns the same name. Some account numbers trigger scripted results. See [Test in the sandbox](/testing/sandbox.md#name-checks).

## When it fails

| Status and code | Cause | Fix |
| - | - | - |
| `422` | A field the chosen `type` needs is missing. | Send the fields listed above. |
| `422 validation_invalid_beneficiary` | An NGN account number that is not 10 digits. | Correct the number. |
| `5xx` | The bank did not answer. | Try again. Do not skip the check. |
