Api Documentation

Bank Codes API Documentation

Overview

The Bank Codes API allows merchants and developers to fetch a list of banks and their codes for a specified country. This is essential for payment integrations, bank selection UIs, and financial operations requiring bank identification.

Purpose: Retrieve up-to-date bank codes by country.
Target Audience: Fintech developers, payment integrators, internal teams building financial products.
Version: v2

Quickstart

Obtain an API bearer token (see Authentication below).
Make a POST request to /api/v2/banks/get-by-country with your country code.
Receive a list of banks and their codes in the response.

Prerequisites

Valid API credentials (bearer token).
Base URL: https://base-url-here.com
Internet access.

Authentication & Authorization

All requests require a valid Bearer Token in the Authorization header.

Login to your dashboard or contact support to obtain your API token.
Include the token in the header: Authorization: Bearer <your_token>

Security Best Practices: Never share your API token. Store it securely. Rotate tokens regularly. Tokens may expire or be revoked for security reasons.

Endpoint Reference

HTTP Method	POST
Endpoint URL	`/api/v2/banks/get-by-country`
Base URL	`https://base-url-here.com`
Description	Fetches a list of banks and their codes for a given country.

Request Headers

Header	Type	Description	Required
Authorization	string	Bearer token	Yes
Accept	string	application/json	Yes
Content-Type	string	application/json	Yes

Request Body

Field	Type	Description	Required
country_code	string	Country code (e.g., KES, TZS)	Yes

{
    "country_code": "KES"
}

Code Samples

curl --location --request POST 'https://base-url-here.com/api/v2/banks/get-by-country' \
--header 'Authorization: Bearer <your_token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "country_code": "KES"
}'

Success Response

Field	Type	Description
success	boolean	Indicates if the request was successful
message	string	Response message
data	array	List of bank objects

{
    "success": true,
    "message": "Successfully initiated",
    "data": [
        {
            "name": "UBA Kenya Bank Ltd",
            "currency": "KES",
            "code": "76"
        },
        {
            "name": "Victoria Commercial Bank Ltd",
            "currency": "KES",
            "code": "54"
        }
    ]
}

Error Responses

Status Code	Example	Description
400	{"success": false, "message": "Invalid country code."}	Bad Request
401	{"success": false, "message": "Unauthorized."}	Missing or invalid token
429	{"success": false, "message": "Rate limit exceeded."}	Too many requests
500	{"success": false, "message": "Internal server error."}	Server error

Data Model: Bank Object

Field	Type	Description
name	string	Bank name
currency	string	Currency code (e.g., KES)
code	string	Bank code

Rate Limiting

Default: 1500 requests per second. Exceeding this returns HTTP 429 with a Retry-After header.

This endpoint is rate limited to prevent abuse and ensure fair usage.

If you need more requests, please contact support.

Versioning

This endpoint is part of API version v2. For future changes, refer to the changelog.

Terms of Use & Legal

By using this API, you agree to our Terms of Service and Privacy Policy. Do not share sensitive data or credentials.