Select a provider for a payment

Choose which provider or bank is used to pay.

A bank_transfer cannot happen without a provider or bank to pay with. How you or your user chooses what provider to pay with depends on the value you choose for provider_selection when you create a payment. provider_selection is an object under the payment_method type bank_transfer.

There are two options to choose from for provider_selection:

  1. user_selected
  2. preselected

When you create a payment, in most circumstances the user chooses the PIS provider they want to pay with before they are redirected to their provider's website or app.

When you use user_selected, the flow looks like this:

When you use preselected, the flow is shortened like this:

We strongly recommend you use user_selected unless you have a specific reason to choose preselected instead. For example, if your user has already made a payment and you want to streamline the process for future payments, you might want to use preselected.

The providers you can create a payment with are limited to the banks in the region where the payment is made.

The user_selected provider selection method

A typical request body for a payment you create with user_selected as the provider_selection type is as below:

{
  "amount_in_minor": 100,
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected"
    },
    "beneficiary": {
      "type": "external_account",
      "account_holder_name": "Jane Doe",
      "reference": "some-reference",
      "account_identifier": {
        "type": "sort_code_account_number",
        "sort_code": "123456",
        "account_number": "12345678"
      }
    }
  },
  "user": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

When a payment is created with user_selected as the provider_selection type, two action types will become available during authorisation of the payment.

If you are using the hosted payment page, embedded payment page, iOS SDK or Android SDK to authorise the payment, these actions will be taken care of for you.

Filter provider_selection

You can filter which providers the user can select during payment authorisation.

A request body for the user_selected type with a filter looks like this:

{
  "amount_in_minor": 100,
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
      "filter": {
        "countries": ["GB"],
        "release_channel": "live"
      }
    },
   .
   .
   .
}

🚧

We do not recommend that you use the countries or release_channel filters unless you have a specific use case in mind.

Countries

You can provide one or more two-letter country codes for the filter.countries object as an array to limit the countries returned in the payment response. Use this filter to limit the providers the user can select to providers from your preferred countries.

For more information on the providers we support by country, see the Help Centre.

Release channel

You can provide one of three values for the filter.release_channel to change the providers that your payment response returns:

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 live.
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 live.
liveLive 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 live providers.
Payment response includes providers in live.

The preselected provider selection method

Using a preselected provider ensures that the payment is initiated with a specific provider that TrueLayer supports. You can retrieve these providers from one of our v2 endpoints. Learn more about payment providers and how to use the /providers endpoint.

A typical request body for a payment created with this provider_selection type will look like the following:

{
  "amount_in_minor": 100,
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "preselected",
      "provider_id": "ob-monzo", 
    "scheme_selection": {
      "type": "faster_payments_service",
      }
    },
    "beneficiary": {
      "type": "external_account",
      "account_holder_name": "Jane Doe",
      "reference": "some-reference",
      "account_identifier": {
        "type": "sort_code_account_number",
        "sort_code": "123456",
        "account_number": "12345678"
      }
    }
  },
  "user": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

Choosing the type of provider_selection removes the provider_selection action from the user authorisation flow. The user will be redirected straight to a provider.

If you select preselected as the provider selection method, you can also preselect the remitter's payment details. This is useful if you want to ensure a payment comes from a specific account.

The format of the remitter object is the same as the beneficiary object. You need to provide an account_holder_name and an account_identifier of sort_code_account_number, iban, bban or nrb.

📘

Spanish preselected payments

If you are accepting payments in Spain, and these things are true:

  • you initiate payments from a preselected provider
  • your user has an existing connection to the Data API

we recommend also passing the corresponding data access token within the remitter object. If you don't do this, the Data connection to your user's bank will fail and they will need to authorise the connection again.

Passing an access token also streamlines the authorisation process for your user by enabling them to skip one of bank login or SCA, depending on the provider.

For more detailed instructions on passing a data access token, see the API reference.

Scheme selection

As part of selecting a provider, you also specify how scheme selection works as part of a payment. To do this, you provide a value for the provider_selection.scheme_selection object.

Scheme selection is more relevant in Europe, as many European banks support SEPA instant, which settles very quickly, and SEPA credit, which can take several days to settle. By default, all UK payments use the Faster Payments Service, which is an instant scheme. Learn more about payment schemes.

If you don't specify a scheme selection method at payment creation, the payment uses the default scheme for the currency: faster_payments_service for GBP and sepa_credit_transfer for EUR.

Below is an example of a payment with user_selected provider selection with instant_only scheme selection:

{
  "currency": "EUR",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
      "filter": {
        "release_channel": "general_availability",
        "customer_segments": [
          "retail"
        ]
      },
      "scheme_selection": {
        "type": "instant_only",
        "allow_remitter_fee": false
      }
    },
    "beneficiary": {
      "type": "merchant_account",
      "verification": {
        "type": "automated"
      }
    }
  },
  "amount_in_minor": 100
}

📘

Instant payments in the UK

Payments in the UK use Faster Payments (faster_payments_service), which is free and instant. If you only accept payments within the UK, you do not need to set scheme_selection to instant_only to ensure that payments are instant.

Different scheme_selection methods

There are four different methods you can use for scheme selection, explained in the table below. You can only use preselected for scheme selection if provider selection is also preselected.

The behaviour when you select a scheme at payment creation differs, based on whether you the payment uses user_selected or preselected provider selection.

Scheme selection methoduser_selected provider selection behaviourpreselected provider selection behaviour
instant_onlyThe provider selection screen only displays providers that support instant payment schemes. The user cannot select a non-instant scheme.

If the payment fails over the instant payment scheme, instant_only ensures it doesn't fall back to a non-instant scheme.
If the preselected provider supports both instant and non-instant payment schemes, instant_only ensures that the payment will not fall back to a non-instant scheme if it fails.
instant_preferredThe provider selection screen displays providers that support both instant and non-instant payments schemes.

If the instant payment fails, instant_preferred ensures it falls back to a non-instant scheme.
If the preselected provider supports both instant and non-instant payment schemes, instant_preferred ensures that the instant payment falls back to a non-instant scheme if it fails.

If you choose instant_preferred and also specify allow_remitter_fee as false, the payment uses a non-instant scheme if there is a fee for the instant scheme.
user_selectedWith the user_selected scheme selection method, the provider selection screen displays all providers, regardless of whether they support instant or non-instant payment schemes, or both.

After they select a provider, the user sees a screen where they can select between an instant or non-instant payment scheme (if the provider supports both).
With the user_selected scheme selection method, a scheme selection screen displays even though the provider is preselected so no provider selection screen displays.

The scheme selection screen doesn't display if the provider only supports one of instant or non-instant payment schemes.
preselectedYou cannot use preselected scheme selection with user selected provider selection.With preselected provider and scheme selection, neither a provider or scheme selection screen displays. The preselected scheme must be provided from a list of valid schemes.

We recommend you use this combination for returning users who have saved their preferred provider and payment scheme.

🚧

Provider determined schemes

Some providers (for example, Revolut) choose the payment scheme themselves. This is reflected in our API as the provider_determined scheme. TrueLayer authorisation UIs do not display a scheme selection screen for provider_determined providers.

Currently, we do not classify providers using provider_determined schemes as instant providers, as we cannot guarantee that the selected scheme will be instant. Hence, if you use the instant_only variant, these providers will not be included in the provider selection action.

Fees charged for instant payment schemes

Some banking providers charge a fee for payments made over an instant payments scheme. Learn more about potential fees on the Providers page on Console.

If you select instant_only or instant_preferred as the scheme selection method, you should also specify a value for the Boolean allow_remitter_fee child parameter:

  • If true, the provider selection screen shows providers that charge a fee for instant payments.
  • If false, the provider selection screen only shows providers that don't charge a fee for instant payments.

Interaction between instant_preferred and allow_remitter_fee

For a payment where the provider is preselected and you specify instant_preferred for scheme selection, the payment uses an instant scheme if there's no fee, but falls back to a non-instant scheme if there is a fee for instant.