Payment providers

A provider is a bank, or other financial institution, that provides TrueLayer with access to financial data through APIs.

There are several ways to retrieve a list of providers:

• make a POST request to the v2 /single-immediate-payments-providers endpoint
• start the authorisation flow for a user_selected payment
• if you already have an account, go to Console for a full list of providers by country

What the /single-immediate-payments-providers endpoint returns

Use the v2 /single-immediate-payments-providers endpoint to retrieve a list of providers for payments. This list also includes the following information:

• a provider_id for the provider
• provider logos with URLs
• the country the provider is in
• information about applicable payment fees
• the available authorisation methods
• a list of the payments rails supported by the provider
• the current availability of the provider with an error rate

🚧

/single-immediate-payments-providers can be useful when you are creating a customised integration, using the preselected provider selection method to select a provider.

However, if you are integrating for a standard use case with the user_selected provider selection method, we recommend that you do not use the /single-immediate-payments-providers endpoint.

We provide provider logos in SVG format to maximise quality and scalability.

Check our API reference for more information about the v2 version of the /providers endpoint.

Example /single-immediate-payments-providers response

This is an example of the response that the v2 /single-immediate-payments-providers endpoint returns:

{
  "results": [
    {
      "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": "faster_payments_service",
          "fee_options": [
            {
              "fee_option_id": "string",
              "beneficiary_fee": "free",
              "remitter_fee": "free"
            }
          ],
          "requirements": "(Omitted from this example)"
        }
      ],
      "availability": {
        "recommended_status": "healthy",
        "error_rate": 0.5,
        "updated_at": "2023-05-24T13:35:19.883Z"
      }
    }
  ]
}

Use a provider_id to create payments

When you create a payment, you can choose a provider selection method through the provider_selection object:

• The user_selected method enables your user to choose a provider through a provider selection screen.
• The preselected method enables you to specify the provider that the payment should be made through. This can be useful if your user has paid you before and you are remembering their details, or if you have developed your own provider selection method used prior to payment authorisation. To specify a provider, you need to supply a provider_id and scheme_id.

Configure the /single-immediate-payments-providers endpoint

There are four things to consider when you use the /single-immediate-payments-providers endpoint.

Remitter details for EU banks

Some European banks outside of the UK, Ireland, and France may require remitter details. To use these providers, you need to collect the remitter's account details. If you don't collect these details, the payment fails.

Provide the remitter's account details in the payment_method.provider_selection.remitter object (which only displays if you use preselected as the provider selection method).

To see if a provider needs remitter account details, check the response of the /single-immediate-payments-providers endpoint. If they are required, the value of the following Boolean parameter in the response is true:

results.single_immediate_payment_schemes.requirements.single_immediate_payment.remitter.mandatory

Possible authorisation flow types

Most integrations use redirect as the value for the auth_flow_type object. However, you can also use embedded to return providers that use an embedded authorisation flow.

Payment rails and schemes

The /single-immediate-payments-providers endpoint returns the payment rails that a provider supports. The supported payment rails are returned as scheme_id in the results.single_immediate_payment_schemes object. Each payment rail is represented by a scheme_id.

The faster_payments_service and sepa_credit_transfer_instant payment rails are considered instant, as payments on them settle within seconds or minutes. The sepa_credit_transfer payment rail isn't considered instant, as payments on it take 1-3 days to settle.

When you create a payment, you can choose four different options for how the scheme is selected. You select the options by providing the scheme selection method in the payment_method.scheme_selection.type object.

Provider availability

🚧

This feature is in beta, so its functionality may change.

Rarely, banks undergo planned maintenance or even unplanned downtime which cause any payments made through them to fail. The Payments API returns the availability of each provider whenever you:

• make a request to the /single-immediate-payments-providers endpoint
• start an auth flow for a user_selected payment

This information is returned in the availability object, which contains three objects, explained below. We recommend that you poll for provider availability once per minute.

For the best user experience, we recommend that you disable unhealthy banks on your provider selection UI. This is handled for you if you use one of our prebuilt authorisation UIs (hosted and embedded payment pages or SDKs).

If you are using the HPP, EPP or mobile SDKs, unhealthy banks are disabled and display at the bottom of the list of providers. Users who search specifically for an unhealthy provider see it at the top of the list in the disabled state.