Branch selection for payments

Many European banks require you to specify a branch, as well as a provider, when your user authorises a payment.

The Payments API v3 supports branch selection through provider discovery, payment creation, and user account selection flows.

You can:

find out which providers require branch information before payment creation
preselect a branch when creating a payment with a preselected provider
display branch information for returning users with saved accounts
receive branch data in payment responses and webhooks

Use branch selection when you need to create payments with providers that require branch information. This is particularly common in certain European markets where bank account identification includes branch codes.

You can discover which providers require branch information by using the /v3/payments-providers/search endpoint with the appropriate filters.

If you already have the ID of the branch that your user wants to pay with, you can use it inside the branch_selection object within a Create Payment request.

Branch selection in providers endpoints

To find out which providers support or require branch information, make a POST request to the /v3/payments-providers/search endpoint.

To find the branch list for all providers, include an empty branches object in the authorization_flow.provider_selection parameter. If you don’t include the branches object, you won’t receive any branch information.

POST /v3/payments-providers/search HTTP/1.1
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}
Host: api.truelayer-sandbox.com

{
  "authorization_flow": {
    "provider_selection": {
      "branches": {}
    }
  },
  "capabilities": {
    "payments": {
      "bank_transfer": {}
    }
  }
}

The response includes provider details with branch information requirements in the provider capabilities, as in the example below.

{
  "items": [
    {
      "id": "stet-banque-populaire",
      "display_name": "Banque Populaire",
      "icon_uri": "...",
      "logo_uri": "...",
      "country_code": "FR",
      "capabilities": {
        "payments": {
          "bank_transfer": {
            //...
          }
        }
      },
      "branches": [
        {
          "id": "stet-banque-populaire-alsace-lorraine-champagne",
          "display_name": "Alsace Lorraine Champagne",
          "search_aliases": ["al-lo-cha", "champ-branch"]
        },
        {
          "id": "stet-banque-populaire-aquitaine-centre-atlantique",
          "display_name": "Aquitaine Centre Atlantique",
          "search_aliases": ["aq-ce-atl"]
        }
      ]
    }
  ]
}

The fields for each branch include:

Parameter	What it means
`id`	The `branch_id`
`display_name`	The name that appears on the branch selection screen
`search_aliases`	Any text that the user can input into the search box

You can also include an empty branches object in the authorization_flow.provider_selection object when calling POST /v3/payments. The authorization_flow object looks like this:

"authorization_flow": {
  "provider_selection": {
    "branches": {}
  },
  // ...
}

Preselecting a branch at payment creation

If you know which branch your user wants to use, you can preselect it when creating a payment alongside a preselected provider. This creates a smoother user experience for returning customers.

Include the branch_selection object in payment_method.provider_selection when you create a payment. Inside that object, specify the branch_id —

POST /v3/payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: {RANDOM_UUID}
Tl-Signature: {SIGNATURE}
Authorization: Bearer {ACCESS_TOKEN}
Host: api.truelayer-sandbox.com

{
  "amount_in_minor": 30000,
  "currency": "EUR",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "preselected",
      "provider_id": "ob-example-bank",
      "branch_selection": {
        "branch_id": "12345"
      }
    },
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
    }
  },
  "user": {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
    "name": "Anna Schmidt",
    "email": "[email protected]"
  }
}

Branch selection for returning users

For returning users who have previously made payments, the Payments API can return saved account information including branch details through the user_account_selection action.

When the authorisation flow returns a user_account_selection action, the saved accounts include branch_id if the provider supports separate branches:

{
  "authorization_flow": {
    "actions": {
      "next": {
        "type": "user_account_selection",
        "accounts": [
          {
            "id": "account-12345",
            "provider_id": "ob-example-bank",
            "branch": {
								"id": "stet-credit-agricole-anjou-maine",
								"display_name": "Anjou Maine",
								"search_aliases": [
								"AGRIFRPP879"
								]
								}
            "account_identifiers": [
              {
                "type": "iban",
                "iban": "DE89370400440532013000"
              }
            ]
          }
        ]
      }
    }
  }
}

GET Payment

Once a payment is authorised, you can retrieve branch information from the payment details.

Make a GET request to the /v3/payments/{id} endpoint to retrieve payment details including the branch_id . A successful response looks like this:

{
  "id": "0afd1f6a-f611-48ce-9488-321129bb3a70",
  "amount_in_minor": 1,
  "currency": "GBP",
  "user": {
    "id": "f9b48c9d-176b-46dd-b2da-fe1a2b77350c"
  },
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
      "filter": {},
      "scheme_selection": {},
      "provider_id": "eg-provider",
      "branch_selection": {
        "type": "user_selected",
        "branch_id": "branch-a"
      },
      "scheme_id": "payment_scheme"
    },
    "beneficiary": {},
    "retry": {}
  },
  "created_at": "2026-04-12T09:38:51Z",
  "metadata": {
    "prop1": "value1",
    "prop2": "value2"
  },
  "related_products": {
    "signup_plus": {}
  },
  "sub_merchants": {
    "ultimate_counterparty": {}
  },
  "user_consent": {
    "type": "precaptured",
    "captured_at": "2026-04-12T09:38:51Z"
  },
  "status": "authorization_required"
}

You receive branch information for any payment which has reached the authorized status or later.

`Branch_id` in webhooks

Payment webhooks from payment_authorised onwards also include the branch_id , if the corresponding payment was made on a branch.

For example, the payment_executed webhook contains:

{
  "type": "payment_executed",
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payment_id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "payment_method": {
    "type": "bank_transfer",
    "provider_id": "ob-example-bank",
    "scheme_id": "sepa_credit_transfer",
    "branch_id": "12345"
  },
  "executed_at": "2021-12-25T15:00:00.000Z"
}

Branch selection in providers endpoints

Preselecting a branch at payment creation

Branch selection for returning users

GET Payment

Branch_id in webhooks

`Branch_id` in webhooks