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

# Get Supported Payout Banks

> Retrieve the list of banks supported for payout setup.

# Get Supported Payout Banks

Returns the list of banks supported for payout setup. Use this endpoint to populate a bank selection UI before calling [Setup Merchant Payout](/api-reference/marketplace/setup-payout) or [Submit KYC](/api-reference/marketplace/submit-kyc).

<Note>
  The `settlement_bank` or `bank_name` field in payout/KYC requests must exactly match the `name` returned by this endpoint. Passing an unrecognised bank name will cause the request to fail.
</Note>

## Query Parameters

<ParamField query="currency" type="string">
  Filter banks by currency. Pass `NGN` to return Nigerian banks only. Omit to return all supported banks across all currencies.
</ParamField>

## Response

```json theme={null}
{
  "success": true,
  "message": "Banks fetched successfully",
  "data": [
    {
      "institution_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Access Bank",
      "currency": "NGN",
      "country_iso_code": "NG",
      "account_number_type": "bank_account_number"
    },
    {
      "institution_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "GTBank",
      "currency": "NGN",
      "country_iso_code": "NG",
      "account_number_type": "bank_account_number"
    },
    {
      "institution_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Zenith Bank",
      "currency": "NGN",
      "country_iso_code": "NG",
      "account_number_type": "bank_account_number"
    },
    {
      "institution_id": "d4e5f6a7-b8c9-0123-defg-234567890123",
      "name": "OPay",
      "currency": "NGN",
      "country_iso_code": "NG",
      "account_number_type": "phone_number"
    }
  ]
}
```

## Response Fields

| Field                 | Type          | Description                                                                                                   |
| --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------- |
| `institution_id`      | string (UUID) | Unique identifier for the bank institution. Can be passed as `gravv_institution_id` for enhanced bank lookup. |
| `name`                | string        | Bank name — pass this as `settlement_bank` or `bank_name` in payout/KYC requests                              |
| `currency`            | string        | Currency the bank supports (e.g. `NGN`)                                                                       |
| `country_iso_code`    | string        | ISO 3166-1 alpha-2 country code (e.g. `NG`)                                                                   |
| `account_number_type` | string        | Account identifier format: `bank_account_number` or `phone_number` (for mobile money)                         |

## Account Number Types

Some financial institutions use phone numbers instead of traditional account numbers:

| `account_number_type` | Description                             | Example       |
| --------------------- | --------------------------------------- | ------------- |
| `bank_account_number` | Traditional 10-digit bank account       | `0123456789`  |
| `phone_number`        | Mobile money account using phone number | `08012345678` |

When displaying the input field, adjust the label based on this value:

* `bank_account_number`: "Account Number"
* `phone_number`: "Phone Number"

## How Bank Data is Stored

When you submit bank details via [Setup Payout](/api-reference/marketplace/setup-payout) or [Submit KYC](/api-reference/marketplace/submit-kyc), the data is stored in the **KycSubmissions** table:

| API Field                                | Storage Location                     |
| ---------------------------------------- | ------------------------------------ |
| `settlement_bank` / `bank_name`          | `KycSubmissions.bank_name`           |
| `account_number` / `bank_account_number` | `KycSubmissions.bank_account_number` |
| `account_name` / `bank_account_name`     | `KycSubmissions.bank_account_name`   |
| `institution_id`                         | Used for Gravv payout routing        |

<Info>
  **Important**: The `KycSubmissions` table is the single source of truth for all bank details. Legacy fields in `Educatorportfolio` are deprecated.
</Info>

## Usage Flow

```
1. GET /marketplace/payout/banks?currency=NGN
   → get list of valid bank names

2. POST /marketplace/merchants/{merchantId}/payout
   → { "country": "NG", "settlement_bank": "<name from step 1>", ... }

   OR

2. POST /marketplace/merchants/{merchantId}/kyc
   → { "id_country": "NG", "bank_name": "<name from step 1>", ... }
```

## Error Codes

| Status | Error                                           | Fix                                 |
| ------ | ----------------------------------------------- | ----------------------------------- |
| `401`  | `Unauthorized`                                  | Include a valid `X-API-Key` header  |
| `500`  | `We encountered a problem while fetching banks` | Temporary issue — retry the request |

<RequestExample>
  ```bash cURL (NGN banks only) theme={null}
  curl -X GET "https://api.khaime.com/api/v1/partner/marketplace/payout/banks?currency=NGN" \
    -H "X-API-Key: pk_sandbox_your_key"
  ```

  ```bash cURL (all banks) theme={null}
  curl -X GET "https://api.khaime.com/api/v1/partner/marketplace/payout/banks" \
    -H "X-API-Key: pk_sandbox_your_key"
  ```
</RequestExample>

## Next Steps

Once you have the bank list:

* Set up payout for your sub-merchant using [Setup Merchant Payout](/api-reference/marketplace/setup-payout)
* Or include bank details in [Submit KYC](/api-reference/marketplace/submit-kyc)