Select a provider for a payment

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:

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.

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.

🚧

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.