Fetching Bank Branches Guide

CROSSFX API · BANK BRANCHES

Collect a branch only when the selected bank requires one.

Fetch the branches configured for a bank and use the returned code when creating a bank beneficiary.

The branch step is conditional: first inspect branch_details_required on the selected bank, then fetch branches only when needed.

Bank scopedBranch codesConditional lookupBeneficiary setup

How it works

Start with a bank_code returned by the Banks API. If that bank requires branch details, use the code in the branch endpoint and submit the selected branch's returned code as account_details.branch_code.

01 · SELECT BANK

Use bank_code

From the Banks API

→

02 · CHECK RULE

Branch required?

branch_details_required

→

03 · FETCH

List branches

Only when required

→

04 · SUBMIT

Use branch_code

On the beneficiary

Scoped to one bank

The bank code is in the path

Each request returns branches for one selected `bank_code`.

Submission-ready codes

Use the returned code

Submit the branch `code` verbatim as `account_details.branch_code`.

Empty is valid

No branches returns an empty list

A bank with no branches returns an empty `data` array rather than an error.

When to use the Bank Branches API

Branch selection

Populate the next field

Load a branch dropdown after the user selects a bank that requires branch details.

Validate branch codes

Submit accepted values

Confirm the branch belongs to the selected bank before creating the beneficiary.

Skip unnecessary steps

Do not collect a branch by default

Banks that do not require branch details should bypass the branch step entirely.

Before you start

Authentication

Use a valid bearer token

See the Authentication Guide.

Bank code

Use a code returned by CrossFX

Get the `bank_code` from the [Fetching Banks List Guide](/fetching-banks-list-guide-2167564m0), preferably for a bank whose `branch_details_required` value is `true`.

List bank branches

List Bank Branches

Branches configured for one bank

`GET /api/v1/banks/{bank_code}/branches`

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

REQUEST & RESPONSE

Send bank_code as a path parameter.

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

Branch decision

The Banks API tells you whether this endpoint should be called at all.

branch_details_required = true

Fetch branches

Call GET /api/v1/banks/{bank_code}/branches, present the returned options, and submit the selected branch's code.

branch_details_required = false

Skip the branch step

Do not collect or submit a branch code. Calling the branches endpoint for a bank with no branches returns an empty list.

IMPORTANT

Do not invent or reuse branch codes.

A branch belongs to a specific bank. A code returned for one bank is not valid against another bank.

Using the response

Each branch contains two values with distinct purposes.

DISPLAY VALUE

name

Show the branch name to the user in your branch selector.

SUBMISSION VALUE

code

Submit this exact value as account_details.branch_code on the beneficiary.

Business rules

RULE 01

Check the bank first

Only fetch branches when branch_details_required is true.

RULE 02

Branch belongs to bank

A branch code returned under one bank cannot be used against another bank.

RULE 03

Use code verbatim

Do not derive branch_code from the branch name or modify the returned value.

Empty branch lists

A successful request for a bank with no branches returns an empty data array.

This is a valid response, not an error.

If branch_details_required was false, an empty branch list is expected and your flow should continue without a branch code.

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
404	`NOT_FOUND`	The bank code is not in the catalogue	Take the code from List Banks.
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

Submit the selected branch

See where `branch_code` is supplied when creating a `BANK` beneficiary.

Sandbox Data & Testing Guide

Test branch reference data

See the branch catalogue and code pattern available in the Sandbox environment.

How it works#

When to use the Bank Branches API#

Before you start#

List bank branches#

Branch decision#

Using the response#

Business rules#

Empty branch lists#

Errors#

Related#