Console

Select a banking provider for payments

Learn about the two types of provider selection and how to return a list of possible provider IDs.

Suggest Edits

A provider is a bank, or other financial institution that TrueLayer can initiate payments from, or access data from, through APIs.

To accept payments through the Payments API, you need to specify the bank, or provider, that the payment will be made through. To do this, you can either let your user decide at payment creation, or provide it for them if you know which provider they will use. Each method has different use cases.

Within the Payments API, provider selection is driven by provider IDs. The Payments API automatically generates a suitable provider screen based on the filters you provide at payment creation if you use a TrueLayer payment authorisation UI . If you build your own authorisation UI , a list of providers and assets are provided when you start the authorisation flow. You can also use a few other methods to return a list of provider IDs .

When to use user_selected or preselected

When you create a payment, there are two provider selection methods you can specify within the provider_selection parameter: user_selected or preselected.

user_selected provider selection

In a payment with user_selected provider selection, your user chooses a provider through a provider selection screen. The list of providers they can select is based on the parameters and filters you specified when you created the payment .

We recommend that you use user_selected provider selection for first-time payments from a user. This enables you to display a filtered list of providers for the user to select from, giving them more options. This can increase conversion if a provider is temporarily unavailable.

An example of the screens that a user would see as part of a payment with `user_selected` provider selection.

An example of the screens that a user would see as part of a payment with user_selected provider selection.

preselected provider selection

In a payment with preselected provider selection you specify the provider the payment is made through, using a provider_id. This means you need to know which provider the user will pay with. Typically, this is because you have stored their preference after a previous payment.

Alternatively, you may have developed your own provider selection screen, based on the information returned by the /v3/payment-providers/search endpoint.

We recommend that you use preselected provider selection for returning payments from a user. When the user creates their first payment, you can store their preferred banking provider and use it to remove the need for provider selection in subsequent payments. You can also store their banking details and prefill the remitter parameter to simplify account selection in future payments.

An example of the reduced number of screens a user would see as part of a payment with `preselected` provider selection.

An example of the reduced number of screens a user would see as part of a payment with preselected provider selection.

Specify provider selection when you create a payment

The format of your payment creation request changes based on the type of provider selection you use.

user_selected provider selection

This is the format of a payment with user_selected provider selection, with the method specified in payment_method.provider_selection.type:

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": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
      "scheme_selection": {
      "type": "user_selected",
      "allow_remitter_fee": false
      }
    },
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
    }
  },
  "user": {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
    "name": "Jonathan Sandbridge",
    "email": "[email protected]",
    "phone": "+447809123456",
    "date_of_birth": "1992-11-28",
    "address": {
      "address_line1": "40 Finsbury Square",
      "city": "London",
      "state": "London",
      "zip": "EC2a 1PX",
      "country_code": "GB"
    }
  }
}

In the payment response, you receive a payment id as well as a resource_token and user id. However, as the payment had user_selected provider selection, this payment id has a set list of providers associated with it, which the user can authorise the payment through. This list of providers is based on whether the payment is in GBP or EUR, and the provider selection filters you applied in your request.

In a payment that uses a TrueLayer web or mobile authorisation UI and user_selected provider selection, an appropriate provider selection screen is rendered for your user. If you build your own authorisation UI , the provider_selection and form actions may be required as part of a user_selected payment.

Filter the list of providers

As part of a user_selected payment, you can filter the list of providers that the user can choose from. You apply the filters within the payment_method.provider_selection.filter parameter. The filter parameter in a user_selected payment looks like this:

{
  //...
    "payment_method": {
      "type": "bank_transfer",
      "provider_selection": {
        "type": "user_selected",
        "filter": {
          "countries": [
            "BE",
            "DE",
            "FR",
            "IE",
            "IT"
          ],
          "release_channel": "public_beta",
          "customer_segments": "retail",
          "provider_ids": [
            "mock-payments-nl-redirect",
            "mock-payments-pl-redirect"
          ],
          "excludes": {
            "provider_ids": [
              "mock-payments-de-embedded",
              "mock-payments-de-redirect-additional-input-text"
        ],
      },
    },
  }
}

These are the available filters:

FilterPossible valuesDescription
countriesTwo-letter ISO 3166-2 country codesThe countries to include providers from on the provider selection screen. Only applies to EUR payments.
release channelprivate_beta, public_beta, general_availabilityThe maturity of the providers to include on the provider selection screen.

general_availability means that providers are fully ready for use.

However, many providers across Europe are in the public_beta or private_beta release channel. You can check on the <a href="https://console.truelayer.com/providers" target="_blank"Providers page in Console</a.
customer_segmentsretail, business, corporateWhether to return banks that cater to individual (retail), business, or corporate clients.
provider_idsAny of the provider IDs returned by the Payments API, provider-related endpoints or Console.Any additional providers to include in the list users can select from in addition to the other filters applied.
excludesAny of the provider IDs returned by the Payments API, provider-related endpoints or Console.Any providers to exclude from the list users can select from, even if they would otherwise be included based on the filters applied.

The release_channel filter for providers

Whether a provider is in general_availability, public_beta, or private_beta depends on the maturity of their integration with us. general_availability is the most mature, and private_beta the least. The table below explains in more detail and outlines how much notice is given to a provider with each classification.

Release channelDescriptionBehaviour when used as a filter
private_betaPrivate beta providers have working integrations that have passed our criteria. However, there may be configuration details you need to be aware of.

Additionally, breaking changes are made to private beta providers more frequently.

This means you need to contact your integration partner to enable these providers for your client_id.		Payment response includes providers in private_beta, public_beta, and general_availability.
public_betaPublic beta providers have been tested by multiple customers, so they are available by default for your client_id.

There is a two-month notice period for any breaking changes to public beta providers.		Payment response includes providers in public_beta and general_availability.
general_availabilityGeneral availability providers are fully ready for use and are available by default for your client_id.

There is a three-month notice period for any breaking changes to general availability providers.		Payment response includes providers in general_availability.

preselected provider selection

This is the format of a payment with preselected provider selection, with the method specified in payment_method.provider_selection.type:

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": 1000,
  "currency": "EUR",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
    "scheme_selection": {
      "type": "user_selected"
    },
      "remitter": {
        "account_holder_name": "John Sandbridge",
        "account_identifier": {
          "type": "iban",
          "iban": "DE78740201006814567316"
        }
      }
    },
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "2a485b0a-a29c-4aa2-bcef-b34d0f6f8d51"
    }
  },
  "user": {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
    "name": "Jonathan Sandbridge",
    "email": "[email protected]",
    "phone": "+44123456789",
    "date_of_birth": "1992-11-28",
    "address": {
      "address_line1": "1, Hardwick Street",
      "city": "London",
      "state": "London",
      "zip": "EC1R 4RB",
      "country_code": "GB"
    }
  }
}

In a preselected payment, you need to specify the provider_id within the provider_selection parameter. This example specifies the mock-payments-gb-redirect sandbox provider.

In the payment response, you receive a payment id as well as a resource_token and user id.

Preselect user account details in the remitter parameter

You can simplify the returning user journey by preselecting their account details within the payment_method.provider_selection.remitter parameter. This simplifies the journey by preselecting the bank account for the user when they authorise a payment with their banking provider. This means that, for example, they don't have to choose between their personal or joint account.

If you integrate a solution that uses the remitter object, ensure that you use sort_code_account_number for GBP payments, and iban for EUR payments. Your integration must be able to identify which currency a payment is made in. This is because the payment_settled webhook for GBP payments includes both an IBAN and SCAN details, but for GBP payments only SCAN works with the remitter object.

This code block contains examples of what the remitter parameter looks like for SCAN and IBAN accounts:

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": "GBP",
  "payment_method": {
    "provider_selection": {
    "type": "preselected",
    "provider_id": "mock-payments-gb-redirect",
    "scheme_selection": {
    "type": "user_selected"
    },
      "remitter": {
        "account_holder_name": "John Sandbridge",
        "account_identifier": {
          "type": "sort_code_account_number",
          "sort_code": "500000",
          "account_number": "12345601"
        }
      }
  },
    "type": "bank_transfer",
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
    }
  },
  "user":
  {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
    "name": "Jonathan Sandbridge",
    "email": "[email protected]",
    "phone": "+447809123456",
    "date_of_birth": "1992-11-28",
    "address":
    {
      "address_line1": "40 Finsbury Square",
      "city": "London",
      "state": "London",
      "zip": "EC2a 1PX",
      "country_code": "GB"
    }
  }
}

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": 1000,
  "currency": "EUR",
  "payment_method": {
    "provider_selection": {
    "type": "user_selected",
    "scheme_selection": {
    "type": "user_selected"
    },
      "remitter": {
        "account_holder_name": "John Sandbridge",
        "account_identifier": {
          "type": "iban",
          "iban": "DE78740201006814567316"
        }
      }
  },
    "type": "bank_transfer",
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "2a485b0a-a29c-4aa2-bcef-b34d0f6f8d51"
    }
  },
  "user":
  {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
    "name": "Jonathan Sandbridge",
    "email": "[email protected]",
    "phone": "+44123456789",
    "date_of_birth": "1992-11-28",
    "address":
    {
      "address_line1": "1, Hardwick Street",
      "city": "London",
      "state": "London",
      "zip": "EC1R 4RB",
      "country_code": "GB"
    }
  }
}

🚧

Some European banks outside of the UK, France, and Ireland require that you provide the user's IBAN, otherwise they fail.

To find out if a providers requires an IBAN for a preselected payment, see if iban is included in this object in the response from the /v3/payment-providers/search endpoint:

capabilities.payments.bank_transfer.schemes.requirements.account_identifier_types


Sandbox banking providers

If you want to test how provider selection or payment authorisation works in our sandbox environment, we offer a range of sandbox providers you can use. Learn more about sandbox providers and how to test payments in the sandbox environment.

Updated 17 days ago