curl -X GET "https://api.khaime.com/api/v1/payout/banks?currency=NGN" \
-H "X-API-Key: pk_sandbox_your_key"
curl -X GET "https://api.khaime.com/api/v1/payout/banks" \
-H "X-API-Key: pk_sandbox_your_key"
Marketplace
Get Supported Payout Banks
Retrieve the list of banks supported for payout setup.
GET
/
payout
/
banks
curl -X GET "https://api.khaime.com/api/v1/payout/banks?currency=NGN" \
-H "X-API-Key: pk_sandbox_your_key"
curl -X GET "https://api.khaime.com/api/v1/payout/banks" \
-H "X-API-Key: pk_sandbox_your_key"
Intro
Returns the list of banks Khaime supports for local payout setup, so you can populate a bank-selection UI and pass back a valid bank identifier.Context
This is a lookup endpoint that feeds Setup Merchant Payout, Update Merchant Payout, and the bank details on Submit KYC — all three requiresettlement_bank/bank_name to exactly match a name this endpoint returns (for NG, that match is validated server-side). Fetch this list before rendering any bank picker rather than hardcoding bank names.
Hows
Query parameters
string
Filter banks by currency — pass
NGN for Nigerian banks only. Omit to return all supported banks across all currencies.Response
{
"success": true,
"message": "Banks fetched successfully",
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"institution_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"gravv_institution_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"paystack_bank_code": "044",
"name": "Access Bank",
"currency": "NGN",
"country_iso_code": "NG",
"account_number_type": "bank_account_number"
},
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"institution_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"gravv_institution_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"paystack_bank_code": null,
"name": "OPay",
"currency": "NGN",
"country_iso_code": "NG",
"account_number_type": "phone_number"
}
]
}
Response fields
| Field | Type | Description |
|---|---|---|
name | string | Bank name — pass this as settlement_bank (payout endpoints) or bank_name (KYC endpoint) |
id | string (UUID) | Khaime’s internal identifier for the bank |
institution_id | string (UUID) | Same value as gravv_institution_id, kept for backward compatibility |
gravv_institution_id | string | null | The bank’s ID for instant-transfer routing — present when the bank supports instant transfers; null if it doesn’t |
paystack_bank_code | string | null | Fallback routing code used when the bank isn’t on the transfer rail directly |
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 | bank_account_number or phone_number |
Account number types
Some institutions (mobile money providers, mainly) use a phone number instead of a traditional account number:account_number_type | Description | Example |
|---|---|---|
bank_account_number | Traditional bank account | 0123456789 |
phone_number | Mobile money account | 08012345678 |
Usage flow
1. GET /payout/banks?currency=NGN
→ get list of valid bank names
2. POST /merchants/{merchantId}/payout
→ { "country": "NG", "settlement_bank": "<name from step 1>", ... }
OR
2. POST /merchants/{merchantId}/kyc
→ { "id_country": "NG", "bank_account": { "bank_name": "<name from step 1>", ... } }
Error cases
| Status | Error | Fix |
|---|---|---|
401 | Missing or invalid X-API-Key header | Include a valid Partner API key |
500 | We encountered a problem while fetching banks | Temporary issue — retry the request |
curl -X GET "https://api.khaime.com/api/v1/payout/banks?currency=NGN" \
-H "X-API-Key: pk_sandbox_your_key"
curl -X GET "https://api.khaime.com/api/v1/payout/banks" \
-H "X-API-Key: pk_sandbox_your_key"
Whys
Exact-match bank names instead of free text. Local transfer rails route by institution, not by whatever a partner happens to type — validatingsettlement_bank against this fixed list at setup time catches typos and unsupported banks before they cause a failed payout later, rather than after money is already in motion.
Two identifiers per bank (gravv_institution_id and paystack_bank_code). Not every Nigerian bank supports instant transfer — some do, others only route through the fallback rail. Exposing both identifiers lets the payout endpoints pick the right path per bank automatically; you don’t need to know or care which one a given bank uses.
Why nots
- Not a live account-name lookup. This returns supported institutions, not a way to verify that a specific account number belongs to a specific account name — Khaime doesn’t expose account-name resolution through this endpoint.
- Doesn’t cover every country a merchant might be in. It’s scoped to the local-bank-transfer markets (
NG,GH,ZA,KE); Stripe Connect countries manage bank accounts entirely inside Stripe’s own onboarding UI, so they never appear here. - A bank appearing here doesn’t guarantee instant settlement. Banks without a
gravv_institution_idstill work for payout, but route over a fallback rail with different settlement timing.
Next Steps
Once you have the bank list:- Set up payout for your sub-merchant using Setup Merchant Payout
- Or include bank details in Submit KYC