Banks API

The Banks API allows you to retrieve lists of banks for specific countries. This is essential for building beneficiary forms and validating bank account information.

Get Banks by Country

Retrieve a list of all banks available for a specific country. This endpoint is commonly used to populate bank selection dropdowns in your application.

Endpoint

Client API Endpoint: GET /api/v1/client/banks/{country_code}

Authentication

This endpoint requires HMAC authentication (Business API Key). Include your API key and signature in the request headers:

x-api-key: <your-api-key>
x-timestamp: <RFC3339-timestamp>
x-signature: <HMAC-signature>

Note: For HMAC authentication details, see the Authentication guide.

Path Parameters

Query Parameters

Supported Country Codes

Common country codes include:

• NG - Nigeria
• US - United States
• CA - Canada
• GB - United Kingdom
• KE - Kenya
• GH - Ghana
• ZA - South Africa

Note: The list of supported countries may vary. Contact support if you need banks for a country not listed here.

Success Response (200 OK)

Returns an array of bank objects:

[
  {
    "id": 1,
    "name": "Access Bank",
    "code": "044",
    "national_bank_code": "044"
  },
  {
    "id": 2,
    "name": "GTBank",
    "code": "058",
    "national_bank_code": "058"
  },
  {
    "id": 3,
    "name": "First Bank of Nigeria",
    "code": "011",
    "national_bank_code": "011"
  },
  {
    "id": 4,
    "name": "Zenith Bank",
    "code": "057",
    "national_bank_code": "057"
  }
]

Response Fields

Error Responses

Example: cURL

# Get banks for Nigeria (Defaults to banks only)
curl -X GET "https://api.sznd.app/api/v1/client/banks/NG" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here"
 
# Get mobile money for Ghana
curl -X GET "https://api.sznd.app/api/v1/client/banks/GH?type=momo" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here"
 
# Get banks for United States
curl -X GET "https://api.sznd.app/api/v1/client/banks/US" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here"
 
# Get banks for Canada
curl -X GET "https://api.sznd.app/api/v1/client/banks/CA" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here"

Example: HTTP Request

GET /api/v1/client/banks/NG HTTP/1.1
Host: api.sznd.app
x-api-key: your_api_key_here
x-timestamp: 2025-01-30T12:20:15Z
x-signature: generated_signature_here
Content-Type: application/json

Use Cases

1. Beneficiary Forms - Populate bank selection dropdowns when users add beneficiaries
2. Account Validation - Use bank codes to validate account numbers before creating beneficiaries
3. Bank Lookup - Display bank names in transaction details and receipts
4. Multi-Country Support - Dynamically load banks based on the user's selected country

Best Practices

1. Cache Results - Bank lists don't change frequently, so consider caching the response to reduce API calls
2. Handle Errors Gracefully - Some country codes may not be supported; provide fallback options
3. Store Bank IDs - Use the id field when creating beneficiaries, as it's more reliable than codes
4. Validate Country Code - Ensure the country code is in ISO 3166-1 alpha-2 format before making the request

Related Endpoints

• Banks API - Get list of banks for a country
• Create Beneficiary - Use bank information when creating beneficiaries

Next Steps

After retrieving the bank list, you can:

1. Create Beneficiaries - Use the bank id or code when creating beneficiary records
2. Validate Accounts - Use the account lookup endpoint to verify account numbers
3. Display Bank Names - Show user-friendly bank names in your UI

For more information, see:

• Beneficiaries API - How to create and manage beneficiaries
• Account Lookup - Verify bank account details