Provider selection for first-time users
Learn about the two types of provider selection and how to return a list of possible provider IDs. See also how to preselect a provider to simplify returning user journeys.
A provider is a bank, or other financial institution that TrueLayer can initiate payments from through APIs.
To accept payments through the Payments API, you need to specify the bank, or provider, that the payment will be made through. To do this, you can either let your user decide at payment creation, or provide it for them if you know which provider they will use. Each method has different use cases.
In particular, we recommend using the preselected
provider selection type in cases where a user has returned to your site or app to pay you, after they have already completed a payment into your merchant account. For more about returning users, see the section below about the returning user journey.
The Payments API automatically generates a suitable provider screen based on the filters you provide at payment creation if you use a TrueLayer payment authorisation UI .
When you create a payment, there are two provider selection methods you can specify within the provider_selection
parameter: user_selected
or preselected
.
The format of your payment creation request changes based on the type
of provider selection you use.
user_selected
provider selection
user_selected
provider selectionIn a payment with user_selected
provider selection, your user chooses a provider through a provider selection screen. The list of providers they can select is based on the parameters and filters you specified when you created the payment .
We recommend that you use theuser_selected
provider selection for first-time payments from a user. This enables you to display a filtered list of providers for the user to select from, giving them more options. This can increase conversion if a provider is temporarily unavailable.
This is the format of a payment with user_selected
provider selection, with the method specified in payment_method.provider_selection.type
:
POST /v3/payments HTTP/1.1
Content-Type: application/json
Idempotency-Key: {RANDOM_UUID}
Tl-Signature: {SIGNATURE}
Authorization: Bearer {ACCESS_TOKEN}
Host: api.truelayer-sandbox.com
{
"amount_in_minor": 30000,
"currency": "GBP",
"payment_method": {
"type": "bank_transfer",
"provider_selection": {
"scheme_selection": {
"type": "user_selected",
"allow_remitter_fee": false
}
},
"beneficiary": {
"type": "merchant_account",
"merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
}
},
"user": {
"id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
"name": "Jonathan Sandbridge",
"email": "[email protected]",
"phone": "+447809123456",
"date_of_birth": "1992-11-28",
"address": {
"address_line1": "40 Finsbury Square",
"city": "London",
"state": "London",
"zip": "EC2a 1PX",
"country_code": "GB"
}
}
}
In the payment response, you receive a payment id
as well as a resource_token
and user id
. However, as the payment had user_selected
provider selection, this payment id
has a set list of providers associated with it, which the user can authorise the payment through. This list of providers is based on whether the payment is in GBP or EUR, and the provider selection filters you applied in your request.
In a payment that uses a TrueLayer web or mobile authorisation UI and user_selected
provider selection, an appropriate provider selection screen is rendered for your user. If you build your own authorisation UI , the provider_selection
and form
actions may be required as part of a user_selected
payment.
Filter the list of providers
As part of a user_selected
payment, you can filter the list of providers that the user can choose from. You apply the filters within the payment_method.provider_selection.filter
parameter. The filter parameter in a user_selected
payment looks like this:
{
//...
"payment_method": {
"type": "bank_transfer",
"provider_selection": {
"type": "user_selected",
"filter": {
"countries": [
"BE",
"DE",
"FR",
"IE",
"IT"
],
"release_channel": "public_beta",
"customer_segments": "retail",
"provider_ids": [
"mock-payments-nl-redirect",
"mock-payments-pl-redirect"
],
"excludes": {
"provider_ids": [
"mock-payments-de-embedded",
"mock-payments-de-redirect-additional-input-text"
],
},
},
}
}
These are the available filters:
Filter | Possible values | Description |
---|---|---|
countries | Two-letter ISO 3166-2 country codes | The countries to include providers from on the provider selection screen. Only applies to EUR payments. |
release channel | private_beta , public_beta , general_availability | The maturity of the providers to include on the provider selection screen.general_availability means that providers are fully ready for use.However, many providers across Europe are in the public_beta or private_beta release channel. You can check on the <a href="https://console.truelayer.com/providers" target="_blank"Providers page in Console</a. |
customer_segments | retail , business , corporate | Whether to return banks that cater to individual (retail), business, or corporate clients. In each payment you filter, you should specify the the segments. you want |
provider_ids | Any of the provider IDs returned by the Payments API, provider-related endpoints or Console. | Any additional providers to include in the list users can select from in addition to the other filters applied. |
excludes | Any of the provider IDs returned by the Payments API, provider-related endpoints or Console. | Any providers to exclude from the list users can select from, even if they would otherwise be included based on the filters applied. |
The release_channel
filter for providers
release_channel
filter for providersWhether a provider is in general_availability
, public_beta
, or private_beta
depends on the maturity of their integration with us. general_availability
is the most mature, and private_beta
the least. The table below explains in more detail and outlines how much notice is given to a provider with each classification.
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 general_availability . |
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 general_availability . |
general_availability | General availability 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 general availability providers. | Payment response includes providers in general_availability . |
The customer_segments
filter for providers
customer_segments
filter for providersWhen you filter providers, you can include an array to decide what type of providers are returned. The three available options are:
retail
: Banks that serve individual consumers.business
: Banks that serve businesses, typically small and medium enterprises.corporate
: Banks that serve large corporations, multinationals, and other large institutional customers.
A common use for this filter is to specify retail
to remove business and corporate banks from provider selection for payments made by customers. Conversely, if the payment is for a B2B business, you might want to filter to display business
and corporate
providers only.
The default behaviour if you don't specify the customer_segments
filter is to return retail providers only.
Updated 14 days ago