Provider selection
Learn about the different methods available to select a provider when you create a payment.
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
:
user_selected
preselected
We strongly recommend you use user_selected
unless you specifically require preselected
.
The user_selected
provider selection method
user_selected
provider selection methodA 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.

Order of events
Filter provider_selection
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
instant_only
scheme selection methodIf 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 usingprovider_determined
schemes as instant providers, as we cannot guarantee that the selected scheme will be instant. Hence, if you use theinstant_only
variant, these providers will not be included in the provider selection action.
The instant_preferred
scheme selection method
instant_preferred
scheme selection methodIf 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
preselected
provider selection methodA 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.

Order of events for a preselected
provider_selection
type
Available scheme_ids
for payments
scheme_ids
for paymentsIf 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.
scheme_id | Description |
---|---|
provider_determined | The bank determines which payment scheme to use for the payment. |
sepa_credit_transfer | The payment is made via SEPA credit transfer. |
sepa_credit_transfer_instant | The payment is made via SEPA instant credit transfer. |
faster_payments_service | The payment is made via the Faster Payment System. |
Learn how to check which schemes different providers support.
Updated about 1 month ago