Select a banking provider for payments

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.

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.

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:

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.

The customer_segments filter for providers

When you filter providers, you can include an array to decide what type of providers are returned. The three available options are:

• retail: Banks that serve individual consumers.
• business: Banks that serve businesses, typically small and medium enterprises.
• corporate: Banks that serve large corporations, multinationals, and other large institutional customers.

A common use for this filter is to specify retail to remove business and corporate banks from provider selection for payments made by customers. Conversely, if the payment is for a B2B business, you might want to filter to display business and corporate providers only.

The default behaviour if you don't specify the customer_segments filter is to return retail providers only.

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": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "preselected",
      "provider_id": "mock-payments-gb-redirect",
      "scheme_selection": {
    "type": "instant_preferred"
    },
      "remitter": {
        "account_identifier": {
          "type": "sort_code_account_number",
          "sort_code": "123456",
          "account_number": "12345678"
        },
        "account_holder_name": "Optional Remitter"
      }
    },
    "beneficiary": {
      "type": "merchant_account",
      "account_holder_name": "Merchant Account name",
      "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57",
      "reference": "testRef 001"
    }
  },
  "metadata": {
    "newKey": "New Value 001 test"
  },
  "user": {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
    "name": "Jonathan Sandbridge",
    "email": "[email protected]",
    "phone": "+44123456789",
    "date_of_birth": "1992-11-28",
    "address": {
      "address_line1": "40 Finsbury Square",
      "city": "London",
      "state": "London",
      "zip": "EC2A 1PX",
      "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.

How bank downtime displays

Sometimes, a bank is unavailable. This can be due to planned downtime, or an outage.

If you use a TrueLayer authorisation UI, it automatically detects if a bank is unavailable and greys out that bank's logo. This gives your user a chance to select a different bank. If you build your own UI, the provider selection response contains the information and assets you need to develop this functionality yourself.

The sandbox environment contains an example of a 'healthy' and 'unhealthy' provider, with these provider IDs:

• mock-payments-gb-redirect
• mock-payments-gb-redirect-unhealthy

You can use these providers to test how bank downtime displays in your authorisation flow.

If you want to be notified when a bank is experiencing or has planned downtime, you can subscribe to receive email alerts from TrueLayer here.