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 minute. Exceeding this returns HTTP 429 with a Retry-After header.

Versioning

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

Support & Feedback

For help, contact support@support.africa.
Feedback on this documentation? Let us know.

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.