Use the single-immediate-payments-providers endpoint [Payments V2]

🚧

The information returned by the /v2/single-immediate-payments-providers endpoint is still accurate and can be used with the Payments API v3.

However, we recommend you use the more recent /v3/payment-providers/search endpoint for all new integrations.

If you want to return a list of providers and the id for each of them, you can make a GET request to the /v2/single-immediate-payments-providers endpoint.

Configuring the 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 schemes

The /single-immediate-payments-providers endpoint returns the payment schemes 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.

Provider availability

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.

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

For more information about scheme selection, see [Select a payments scheme for payments].

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.

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"
      }
    }
  ]
}