--- updatedAt: 2026-08-26T12:10:25.000Z agentTools: projectIndex: https://docs.truelayer.com/llms.txt --- # Branch selection for payments Many European banks require that your users specify their branch authorises a payment. 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`](https://docs.truelayer.com/reference/search-payment-providers) 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. ```jsx 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. ```jsx { "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: ```jsx "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](https://docs.truelayer.com/docs/create-a-payment). Inside that object, specify the `branch_id` — ```jsx 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": "anna@example.com" } } ``` ### 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: ```jsx { "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}`](https://docs.truelayer.com/reference/get-payment-1) endpoint to retrieve payment details including the `branch_id` . A successful response looks like this: ```json { "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`](https://docs.truelayer.com/docs/payment-webhooks#payment_executed) webhook contains:  ```jsx { "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" } ```