Get Supported Payout Banks

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 require settlement_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`

Switch your input field’s label based on this value — “Account Number” vs. “Phone Number” — rather than assuming every institution uses the same format.

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_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/marketplace/payout/banks?currency=NGN" \
  -H "X-API-Key: pk_sandbox_your_key"

curl -X GET "https://api.khaime.com/api/v1/marketplace/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 — validating settlement_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_id still 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

API Reference

Account

Products & Pricing

Payments

Integration Guides

Commerce API

Subscriptions

Marketplace

Intro

Context

Hows

Query parameters

Response

Response fields

Account number types

Usage flow

Error cases

Whys

Why nots

Next Steps

​Intro

​Context

​Hows

​Query parameters

​Response

​Response fields

​Account number types

​Usage flow

​Error cases

​Whys

​Why nots

​Next Steps

Intro

Context

Hows

Query parameters

Response

Response fields

Account number types

Usage flow

Error cases

Whys

Why nots

Next Steps