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 condition is that a provider must be selected. How a provider is selected depends on the value you chose 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 :

• private_beta
• public_beta
• general_availability

Of these, private_beta 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, private_beta includes all channels, while public_beta includes only public_beta and general_availability.

Scheme selection

When using the user_selected provider selection method, you may optionally set the scheme_selection field to guide which payment scheme will get picked for the transaction.

An example provider and scheme selection will look like the following

"provider_selection": {
  "type": "user_selected",
  "filter": {
    "countries": ["FR"]
  },
  "scheme_selection": {
    "type": "instant_only",
    "allow_remitter_fee": true
  }
}
.
.
.

📘

Instant payments in the UK

Note that payments in the UK use faster_payments_service, which is free and instant.

Therefore, you do not need to set scheme_selection to achieve instant payments if you are only integrating for GBP payments.

Currently, there are two explicit options available. If you do not explicitly set this field, payments will use the default scheme for the respective currency (faster_payments_service for GBP and sepa_credit_transfer for EUR).

The instant_only scheme selection method

If you use this type, we only return providers that support instant payments. Additionally, whatever provider the user chooses will use instant payments instead of any alternatives they support. Instant payments methods include faster_payments_service for GBP and sepa_credit_transfer_instant for EUR.

Many EU providers may charge the remitter a fee for using instant payments. These providers are not returned in the provider selection action by default. To include them, you can set the allow_remitter_fee flag to true.

🚧

Provider determined schemes

Some providers (e.g. Revolut) choose the payment scheme themselves. This is reflected in our API as the provider_determined scheme. 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.

The instant_preferred scheme selection method

If you use this type, we only return providers that match the filters, regardless of whether they support instant payments or not, in the provider selection action. Once the user selects the provider, we will attempt to pick an instant scheme if available. Else, we will use the currency default scheme.

Many providers may charge the remitter a fee for using instant payments. By default, we will not select an instant scheme if this is the case. To allow instant schemes to be selected even if a remitter fee may be charged, you can set the allow_remitter_fee flag to true.

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

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 scheme_id field refers to the payment scheme a payment should use, for example faster payments in the UK, or SEPA instant in Europe.

The values currently available for the scheme_id field are below.

Learn how to check which schemes different providers support.