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": "general_availability"
}
},
.
.
.
}
We do not recommend that you use the
countries
orrelease_channel
filters unless you have a specific use case in mind.
Countries
Limits your user's selection options to providers from the countries
of your choice.
Currently you can set countries
as GB
, IE
or FR
. If left empty, the call includes all three countries.
For more information on the providers we support by country, see the Help Centre.
Release channel
The available release channels are:
alpha
private_beta
public_beta
general_availability
alpha
includes all channels. private_beta
includes channels in private and public beta and general availability, but not channels in alpha. public_beta
includes only channels in public beta and general availability.
Scheme selection
When using the user_selected
provider selection method, set the scheme_selection
field to indicate which payment scheme will be used for the transaction.
An example provider and scheme selection looks like this:
"provider_selection": {
"type": "user_selected",
"filter": {
"countries": ["FR"]
},
"scheme_selection": {
"type": "instant_only",
"allow_remitter_fee": true
}
}
.
.
.
Instant payments in the UK
Payments in the UK use Faster Payments (
faster_payments_service
), which is free and instant. If you only plan on making payments within the UK, you do not need to setscheme_selection
for instant 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).
instant_only
instant_only
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 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.
instant_preferred
instant_preferred
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 select an instant scheme if available. Otherwise, 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, set the allow_remitter_fee
flag to true
.
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.
remitter
selection
remitter
selectionA 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]"
}
}
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_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.
The scheme_id
field refers to the payment scheme a transaction uses. For example:
- Faster Payments in the UK
- SEPA Instant in Europe.
The values that you can select 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 Payments Service. |
Learn how to check which schemes different providers support.
Updated 20 days ago