Use the providers endpoint

In this page, you'll find out how to:

• Use /providers to get your required provider ID.
• Use a preselected provider ID to set a provider for a payment.

❗️

Warning

This page is only for clients with a customised integration path, using the preselected method for provider_selection. You should not follow this path for standard use cases with the `user_selected' method.

Get providers

You can check our API reference for more information about the v2 and v3 versions of the /providers endpoint.

To find out available provider_ids you can use TrueLayer's v2 /providers endpoint, which provides a database of providers TrueLayer supports, alongside a lot of useful authorisation data about the provider.

You can use the provider IDs the /providers endpoint returns when you set the provider_selection to preselected when you create a payment.

As v3 is currently in private beta, we do not provide the /providers endpoint natively on our API.

Example provider

{
      "provider_id": "ob-revolut",
      "logo_url": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/revolut.svg",
      "icon_url": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/revolut.svg",
      "display_name": "Revolut",
      "country": "GB",
      "divisions": [
        "retail"
      ],
      "single_immediate_payment_schemes": [
        {
          "scheme_id": "provider_determined",
          "requirements": ...
        }
      ],
      "release_stage": "live"
    }

Pass the provider_id field from the response to provider_selection.provider_id if the provider type in the payment_method is set as preselected.

Set a provider for a payment

You can set a provider for a payment instead of letting your user choose a provider. This bypasses the provider_selection action. To do so, set the type of the provider_selection field as preselected:

{
  "amount_in_minor": 1,
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "preselected",
      "provider_id": "YOUR_PRESELECTED_PROVIDER_ID",
      "scheme_id": "SCHEME_ID_YOUR_PRESELECTED_PROVIDER_SUPPORTS"
      }
    }
}

Configuration considerations

There are a few things you should consider when you use the /providers endpoint.

Regions outside of the UK, France, and Ireland

Currently, regions outside of the UK, Ireland and France are not officially supported. As such, flows may not function as expected.

Remitter details for EU banks

Some European banks, outside of the UK, Ireland, and France, may require remitter details. If you want to use providers from those regions, you need to collect the remitter (sender) account details from the user. You then provide these details in payment_method.provider.remitter when you've selected provider_selection.preselected. If you don't provide the remitter details, the payment may fail.

To check if a provider requires remitter details, check whether they're mandatory in the response of providers endpoint. You can find this information in this field of the response:

single_immediate_payment_schemes.requirements.single_immediate_payment.remitter.mandatory

Correct auth_flow_type for v2 providers endpoint

When you use the v2 providers endpoint to get the list of providers, you should use redirect as the value for the auth_flow_type object.

Available values for scheme_id

When you use provider_selected.preselected, you must provide a valid scheme_id. The /providers endpoint returns the schemes that a provider supports.

The values currently available for the scheme_id field are below.