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 (7,261+ banks with routing numbers)
• CA - Canada
• GB - United Kingdom
• KE - Kenya
• GH - Ghana
• ZA - South Africa
• SL - Sierra Leone
• CI - Côte d'Ivoire

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. The response structure varies by country:

Standard Response (Most Countries)

[
  {
    "id": 1,
    "name": "Access Bank",
    "code": "044",
    "national_bank_code": "044"
  },
  {
    "id": 2,
    "name": "GTBank",
    "code": "058",
    "national_bank_code": "058"
  }
]

US Banks Response (Includes Additional Fields)

US banks include additional fields for routing numbers and location information. Note that code and national_bank_code are empty strings for US banks:

[
  {
    "id": 1,
    "name": "Federal Reserve Bank of Boston",
    "code": "",
    "national_bank_code": "",
    "routing_number": "011000015",
    "short_name": "FRB-BOS",
    "state_code": "MA",
    "state_name": "Massachusetts"
  },
  {
    "id": 2,
    "name": "State Street Boston",
    "code": "",
    "national_bank_code": "",
    "routing_number": "011000028",
    "short_name": "STATE ST BOS",
    "state_code": "MA",
    "state_name": "Massachusetts"
  },
  {
    "id": 3,
    "name": "Bank of New York",
    "code": "",
    "national_bank_code": "",
    "routing_number": "011001234",
    "short_name": "BK OF NYC",
    "state_code": "NY",
    "state_name": "New York"
  }
]

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 (includes routing numbers)
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/routing numbers 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
5. US Bank Routing - Use routing numbers for ACH and wire transfers in the United States
6. State Filtering - Filter US banks by state code for location-specific bank selection

US Banks Specific Information

The US banks list includes 7,261+ banks with complete routing number information:

• Routing Numbers: Each bank entry includes a 9-digit ABA routing number (use routing_number field, not code)
• State Information: Banks are tagged with their state code and full state name
• Short Names: Abbreviated bank names for display in compact UIs
• Full Names: Complete bank names for official documentation
• Code Fields: For US banks, code and national_bank_code are empty strings - always use routing_number instead

Important Notes for US Banks:

• code and national_bank_code fields are empty strings ("") for US banks
• Always use the routing_number field for US bank identification and transactions
• Use routing_number for ACH and wire transfer setup
• Filter banks by state_code for location-specific bank selection

Example Use Cases for US Banks:

• Filter banks by state when users select their location
• Display routing numbers for ACH setup instructions
• Validate routing numbers before processing transfers
• Show bank short names in dropdown menus, full names in confirmations

Look up US bank by routing number (client)

Look up US bank details by ABA routing number. Use this when you have a routing number (e.g. from user input or a partner) and need the bank name and location. Response is USD-focal only: no id, code, or national_bank_code.

Endpoint

Client API Endpoint: GET /api/v1/client/banks/US/routing-lookup/{routing_number}

Authentication

HMAC authentication (Business API Key). Same as Get Banks by Country.

Path parameters

Success response (200 OK)

Array of matching US bank objects. Multiple entries may be returned when the same bank has multiple routing numbers (e.g. by branch).

Example response:

[
  {
    "name": "JPMORGAN CHASE BANK, NATIONAL ASSOCIATION",
    "short_name": "CHASE",
    "state_code": "DE",
    "state_name": "Delaware",
    "routing_number": "021000021"
  }
]

Error responses

Example: cURL

curl -X GET "https://api.sznd.app/api/v1/client/banks/US/routing-lookup/021000021" \
  -H "x-api-key: your_api_key_here" \
  -H "x-timestamp: 2025-01-30T12:20:15Z" \
  -H "x-signature: generated_signature_here"

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
5. Filter by Type - Use the type parameter to filter between banks and mobile money providers when needed
6. US Routing Numbers - For US banks, always use the routing_number field for ACH and wire transfers (not code or national_bank_code)
7. Handle Empty Codes - For US banks, expect code and national_bank_code to be empty strings and use routing_number instead

Related Endpoints

• Banks API - Get list of banks for a country (this endpoint)
• Look up US bank by routing number - Get US bank details by ABA routing number (client)
• Account Lookup - Verify bank account details using bank codes
• 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 (use routing_number for US banks)
2. Validate Accounts - Use the account lookup endpoint to verify account numbers
3. Display Bank Names - Show user-friendly bank names in your UI
4. US Transfers - Use routing numbers for ACH and wire transfer setup

For more information, see:

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