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
:
user_selected
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
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 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
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
orrelease_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 channel | Description | Behaviour when used as a filter |
---|---|---|
private_beta | Private 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_beta | Public 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 . |
live | Live 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
preselected
provider selection methodUsing 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 setscheme_selection
toinstant_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 method | user_selected provider selection behaviour | preselected provider selection behaviour |
---|---|---|
instant_only | The 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_preferred | The 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 payment will not fall back to a non-instant scheme if it fails. |
user_selected | With 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. |
preselected | You 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 forprovider_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 theinstant_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.
Updated 14 days ago