Provider selection

When you create a payment, you can choose a PIS provider. To do so, use the provider_selection object under the payment_method type bank_transfer. Providers are currently limited to the banks in the region where the payment is being made.

For a bank_transfer to be successful, one conditions is that a provider is selected.
How a provider is selected depends upon the value you choose for provider_selection when you created the payment.

There are two different options for provider_selection:

1. user_selected
2. preselected

We strongly recommend you use user_selected unless you specifically require preselected.

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 Hosted 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 also filter which providers will be enabled during the authorisation of the payment when provider_selection action is being handled by Hosted Payment Page, iOS SDK or Android SDK, or by your frontend components directly for direct integration.

A request body for user_selected type with a filter is as below:

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

Filter options

We do not recommend you use to filter options other countries or release_channel unless you have a specific use case in mind.

1. Countries

You can limit the providers to be from the countries of your choice.

Currently you can set countries to be GB, IE or FR. If left empty, the call includes all three countries.

2. Release Channel

You can configure the release channel you want the providers to be included in.

Currently available release channels in order of lifecycle are :

• alpha
• private_beta
• public_beta
• general_availability

Of these, alpha is the earliest, and general_availability the most mature channel.

If you set the channel to one of these values, the providers include all the channels under the value in the above list.

For example, alpha includes all channels, while public_beta includes only public_beta and general_availability.

🚧

Currently, only Great Britain, Ireland and a subset of France providers are available.

If you need to set a country filter for the provider selection, you can only choose these three countries.

preferred scheme ids

You can state which payment schemes you prefer the payment to be made over using the optional preferred_scheme_ids field. You can specify your preferred schemes as an array ordered by descending preference.

Since some schemes are only supported by certain providers, and the user selects a provider at a later stage of the payment, we cannot guarantee that a scheme from your preferred_scheme_ids will be used. If none of the preferred schemes are available on the provider the user selects, we default to an available scheme.

A request body for user_selected type with preferred_scheme_ids looks like:

{
  "amount_in_minor": 100,
  "currency": "EUR",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
      "filter": {
        "countries": ["DE"],
      },
      "preferred_scheme_ids": [
        "sepa_credit_transfer_instant",
        "sepa_credit_transfer"
      ]
    },
   .
   .
   .
}

In this case, we will attempt to initiate the payment using SEPA instant payments. If the provider does not support that scheme, we will try a regular SEPA credit transfer.

🚧

Some schemes may incur a fee to the remitter.

Some banks will charge a fee for payments made over certain schemes, such as sepa_credit_transfer_instant. This fee is paid by the remitter, i.e. the PSU.

The preselected provider selection method

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

This option will set the payment to happen through a specific provider TrueLayer supports. You can retrieve these providers from one of our v2 endpoints. For more, refer to using the providers endpoint.

Choosing the type of provider_selection will essentially remove provider_selection action from the authorisation flow.

Available scheme_ids for payments

Whether you use user_selected or preselected as your provider_selection method, you might need to provide a scheme_id also. The scheme_id field refers to the which payment scheme a payment should use, for example faster payments in the UK, or SEPA instant in Europe.

If you use the user_selected provider selection method, you can provide a scheme_id for the preferred_scheme_ids field to specify your preferred payment schemes.

If you use the preselected provider selection method, you must provide a scheme_id and a provider_id to specify the payment scheme and provider to use for the payment.

The values currently available for the scheme_id field are below.

Learn how to check which schemes different providers support.