Skip to main content
GET
/
marketplace
/
payout
/
banks
curl -X GET "https://api.khaime.com/api/v1/partner/marketplace/payout/banks?currency=NGN" \
  -H "X-API-Key: pk_sandbox_your_key"

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

Returns the list of banks supported for payout setup. Use this endpoint to populate a bank selection UI before calling Setup Merchant Payout or Submit KYC.
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.

​
Query Parameters

​
currency
string
Filter banks by currency. Pass NGN to return Nigerian banks only. Omit to return all supported banks across all currencies.

​
Response

{
  "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

FieldTypeDescription
institution_idstring (UUID)Unique identifier for the bank institution. Can be passed as gravv_institution_id for enhanced bank lookup.
namestringBank name — pass this as settlement_bank or bank_name in payout/KYC requests
currencystringCurrency the bank supports (e.g. NGN)
country_iso_codestringISO 3166-1 alpha-2 country code (e.g. NG)
account_number_typestringAccount 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_typeDescriptionExample
bank_account_numberTraditional 10-digit bank account0123456789
phone_numberMobile money account using phone number08012345678
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 or Submit KYC, the data is stored in the KycSubmissions table:
API FieldStorage Location
settlement_bank / bank_nameKycSubmissions.bank_name
account_number / bank_account_numberKycSubmissions.bank_account_number
account_name / bank_account_nameKycSubmissions.bank_account_name
institution_idUsed for Gravv payout routing
Important: The KycSubmissions table is the single source of truth for all bank details. Legacy fields in Educatorportfolio are deprecated.

​
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

StatusErrorFix
401UnauthorizedInclude a valid X-API-Key header
500We encountered a problem while fetching banksTemporary issue — retry the request
curl -X GET "https://api.khaime.com/api/v1/partner/marketplace/payout/banks?currency=NGN" \
  -H "X-API-Key: pk_sandbox_your_key"

​
Next Steps

Once you have the bank list: