Fetching Banks List Guide

CROSSFX API · BANKS

Build bank selectors from supported payout data.

Fetch the banks CrossFX can pay out to in a country, together with the exact bank code and whether branch details are required.

Use the response to drive your beneficiary form dynamically rather than maintaining your own bank catalogue or branch rules.

Country scopedBank codesBranch rulesBeneficiary setup

How it works

Send a payout-market country_code. CrossFX returns the supported banks for that country, including the exact code to submit on the beneficiary and the branch requirement for each bank.

01 · MARKET

Send country_code

→

02 · CROSSFX

Supported banks

Name · code · branch rule

→

03 · BENEFICIARY

Submit bank_code

account_details.bank_code

Scoped by country

One payout market at a time

Each request returns the banks configured for one `country_code`.

Branch-aware

Ask only when required

`branch_details_required` tells your application whether a branch must be collected for that bank.

Submission-ready codes

Use the returned code

Submit the bank's `code` verbatim as `account_details.bank_code`.

When to use the Banks API

Bank selection

Populate a beneficiary form

Build a bank dropdown using values that CrossFX can currently accept for that payout market.

Dynamic branch fields

Show the right fields

Decide at runtime whether the selected bank requires a branch.

Pre-submit validation

Validate before creating

Confirm the bank code belongs to the beneficiary's country before sending the beneficiary request.

Before you start

Authentication

Use a valid bearer token

See the [Authentication Guide](/authentication-guide-2385173m0).

Country code

Use ISO-3166 alpha-2

You need the payout market's `country_code`, for example `KE`.

List banks

List Banks

Banks available for a payout market

`GET /api/v1/banks`

Open the API Reference for the full request and response schemas and an interactive console.

REQUEST & RESPONSE

Send country_code as a query parameter.

The response returns data, an array containing name, code and branch_details_required for each bank.

Using the response

The response gives you everything needed to build the bank portion of a BANK beneficiary form.

DISPLAY

name

The bank name to display to your user in the selector.

SUBMIT

code

Submit this exact value as account_details.bank_code.

FORM LOGIC

branch_details_required

Determines whether your beneficiary form should collect a branch.

Branch handling

The selected bank determines whether a branch should appear in your beneficiary flow.

branch_details_required = true

Collect a branch

Call List Bank Branches for the selected bank and let the user choose a valid branch.

branch_details_required = false

Do not send a branch

The bank has no branches in the CrossFX model and rejects any branch code you send.

IMPLEMENTATION PATTERN

Select country → fetch banks → select bank → inspect branch_details_required → fetch branches only when required.

Business rules

RULE 01

Use code verbatim

Do not derive bank_code from the bank name. Submit the exact value CrossFX returns.

RULE 02

Country code is case-sensitive

KE resolves while ke returns 404.

RULE 03

Bank codes are country-specific

A beneficiary is rejected if its bank_code belongs to a different country from the submitted country_code.

Branch rules come from the bank response. Do not make your own assumptions about whether a bank requires a branch.

Errors

Every error below returns the CrossFX platform error envelope, with error first and error_id last.

SUPPORT IDENTIFIER

Keep the error_id

Quote the returned error_id when contacting CrossFX support so the request can be located in platform logs.

HTTP	`code`	Trigger	What you do
422	`VALIDATION_FAILED`	`country_code` is absent, null, or not a string	Send it as a string. The body nests the field under `error.query`.
404	`NOT_FOUND`	The country is not configured	Check the case, then confirm the country is supported.
401	—	The `Authorization` header is missing, malformed, or the token has expired	Request a new token and retry. The body is `{ "message": "Unauthorized" }`.

Create Beneficiary Guide

Use the selected bank

See where the returned `bank_code` is submitted when creating a `BANK` beneficiary.

Sandbox Data & Testing Guide

Test supported banks

See the bank catalogue available in the Sandbox environment.

How it works#

When to use the Banks API#

Before you start#

List banks#

Using the response#

Branch handling#

Business rules#

Errors#

Related#