Build a provider selection screen [Payments V2]

Build the screen your users select a bank on.

To offer open banking payments to your users, you need a provider selection screen. From this screen, your users can select the bank they want to make a payment from. You can build your own provider selection screen with the /v2/single-immediate-payments-providers endpoint.

📘

We do not recommend that you store the information from the /providers endpoint locally as you should expect TrueLayer to update the response returned by the endpoint from time to time. We anticipate updates to happen a few times every quarter.

The providers endpoint serves three purposes:

  1. Displays which banks are currently active (when a bank is temporarily unavailable, we hide them from this list until its service is restored).
  2. Provides the assets to build out a selection screen, for example, logos and display names.
  3. Displays the available schemes, auth flows, and input requirements for each provider.

To get providers whose requirements you support, you have to filter your request using the following query parameters:

FieldAvailable ValuesMandatoryDescription
client_idYour client IDMandatoryRequired for verifying access to providers.
auth_flow_typeredirect
embedded
MandatoryWill only return providers with schemes that support the listed auth flows.
account_typesort_code_account_number
iban
bban
nrb
MandatoryWill only return providers with schemes that support the listed account identifiers.
currencyISO 4217 currency codes
for example, GBP,EUR
MandatoryWill only return providers with schemes that support the listed currencies.
countryISO 3166-1 alpha-2 country codes
for example, GB,FR
OptionalWill only return providers from the listed countries.
additional_input_typetext
select
text_with_image
OptionalWill filter out any provider schemes that require additional_inputs field types not specified (including any on subsequent inputs as part of the embedded flow). If omitted, will only return provider schemes that have no required additional inputs.
release_channellive
public_beta
private_beta
OptionalDetermines which providers to return. If omitted, returns all live providers.

Returns providers for the value you provide, and also any that are more mature. live is the most mature and private_beta is the least mature.

For example, a value of public_beta returns all providers in public_beta and live.

Each bank available will have the following fields:

FieldTypeDescription
provider_idstringThis is the provider ID that you will send us in the create payment request.
logo_urlstringThis is the address of the logo asset in SVG form.
icon_urlstringThis is the address of the icon asset in SVG form.
display_namestringThis is a readable name for the provider.
countrystringThe ISO 3166-1 alpha-2 country code for the provider.
divisionsstring[]This array includes all divisions that are available on this provider, for example, retail and business would indicate you can use this single provider to access both retail and business accounts.
single_immediate_payment_schemesSingleImmediatePaymentScheme[]The array lists the available schemes the provider can use, within each is described the requirements for the fields on the Single Immediate Payment initiation request.

The possible values are in the table below.
release_stagestringThis indicates the product maturity of the provider. live and public_beta providers are visible to everyone, while private_beta providers must be enabled for the client_id provided in the query parameters to be visible.
Values: live, public_beta, private_beta.

SingleImmediatePaymentScheme

FieldTypeDescription
scheme_idstringA unique identifier for the scheme, shared across providers. This should be provided on the single_immediate_payment.scheme_id field on the initiation request.
fee_options
(optional)
FeeOption[]If present, then fees are payable to make a payment on the scheme, and you must choose an option in this list when initiating a payment.

The possible values are in the table below.
requirementsSingleImmediatePaymentRequirements[]Contains at least one set of requirements, one of which should be adhered to in order to create a valid initiation request for the scheme.

The possible values are in the second table below.

FeeOption

FieldTypeDescription
fee_option_idstringA unique identifier for the fee option, shared across providers. This should be provided on the single_immediate_payment.fee_option_id field on the initiation request.
beneficiary_feestringA value to indicate if the beneficiary would pay any fees on the transaction, when using this fee option.
Values: free, payable, unknown
remitter_feestringA value to indicate if the remitter would pay any fees on the transaction, when using this fee option.
Values: free, payable, unknown

SingleImmediatePaymentRequirements

Each property in the requirements object corresponds to an identically named property on the initiation request for a Single Immediate Payment.

The following sections detail the requirement types and how they should be interpreted in order to build a valid initiation request.

FieldChild FieldTypeDescription
auth_flow-AuthFlowRequirementsWhich auth flows are supported and what fields are required/available to initiate a payment for those flows.

The possible values are in the table below.
single_immediate_paymentcurrencyCurrencyRequirementsWhich currencies are supported.

The possible values are in the fourth table below.
single_immediate_paymentbeneficiaryParticipantRequirementsWhich beneficiary details are required/supported.

The possible values are in the fifth table below.
single_immediate_paymentremitter
(optional)
ParticipantRequirementsWhich remitter details are required/supported. If omitted, the scheme does not support receiving remitter details.
single_immediate_paymentreferencesReferenceRequirementsWhich reference types are required/supported.

The possible values are in the sixth table below.

AuthFlowRequirements

FieldTypeDescription
typesstring[]A list of supported auth flow types.
Values: redirect,embedded.
redirect
(optional)
RedirectAuthFlowRequirementsWill be set if redirect is supported.

The possible values are in the table below.
embedded
(optional)
EmbeddedAuthFlowRequirementsWill be set if embedded is supported.

The possible values are in the second table below.

RedirectAuthFlowRequirements

FieldTypeDescription
psu_ip_address_required
(optional)
booleanIndicates if auth_flow.psu_ip_address is required on the initiation request.
data_access_token_supported
(optional)
booleanIndicates if auth_flow.data_access_token can be provided on the initiation request, to maintain long lived consents across products (Data API and Payment API), where the provider only allows a single active consent across both AIS and PIS services.
additional_inputs
(optional)
AdditionalInputsAn optional dictionary of ID to additional inputs that must be collected from the end user to initiate a payment. These inputs should be provided using the same IDs in the auth_flow.additional_inputs string dictionary on the initiation request.

EmbeddedAuthFlowRequirements

FieldTypeDescription
additional_input_typesstring[]A list of additional input field types that may be returned during the embedded authorisation flow (not inclusive of those required on initiation below).
Values: text, text_with_image, select.
additional_inputs
(optional)
AdditionalInputsAn optional dictionary of ID to additional inputs that must be collected from the end user to initiate a payment. These inputs should be provided using the same IDs in the auth_flow.additional_inputs string dictionary on the initiation request.

CurrencyRequirements

FieldTypeDescription
supported_currenciesstring[]A list of ISO 4217 currency codes supported by the provider scheme.

ParticipantRequirements

FieldChild FieldTypeDescription
accounttypesstring[]A list of account types supported by the scheme.
Values: sort_code_account_number, iban, bban, nrb.
name
(optional)
-StringFieldRequirementsAn object detailing the requirements for the name, if omitted then setting the name on the initiation request is not supported for this scheme.
mandatory-boolIf a remitter is required. Not present on beneficiary as that is always mandatory.

ReferenceRequirements

FieldChild FieldTypeDescription
types-string[]A list of supported reference types.
Values: single,separate
single
(optional)
-StringFieldRequirementsWill be set if single is supported. Specifies the requirements for a single reference string for the payment.

The possible values are in the table below.
separate
(optional)
beneficiaryStringFieldRequirementsWill be set if separate is supported. Specifies the requirements for the beneficiary reference string for the payment.
separate
(optional)
remitterStringFieldRequirementsWill be set if separate is supported. Specifies the requirements for the remitter reference string for the payment.

StringFieldRequirements

FieldTypeRequirement Description
mandatorybooleanThe corresponding field on the request is mandatory.
min_lengthintegerThe corresponding field on the request must be at least this many characters.
max_lengthintegerThe corresponding field on the request must be at most this many characters.
regexstringThe corresponding field on the request must match the regular expression.
formatstringA well known format to help you communicate to your client how the field will be validated.
Values: any, numerical, alphabetical, alphanumerical, email

AdditionalInputs

The additional_inputs object on responses is a dictionary of input IDs to an object describing the input required. The structure of the input object differs based on the type property, and can be one of the following:

Input TypeDescriptionCorresponding Request Value
textRequires the end user to enter a string valueThe string value the end user entered
text_with_imageDisplays an image to the end user and requires them to enter a string valueThe string value the end user entered
selectProvides a list of options for the end user to select fromThe id of the selected option

Text input

FieldTypeDescription
typestringValue indicating the field type: text
display_textstringText to describe what the field is asking for (English)
provider_description
(optional)
stringText directly from the bank relating to the field
mandatorybooleanIf the input must be provided
sensitivebooleanIf the input is sensitive (should be masked in UI)
min_lengthintegerThe minimum length of the input text
max_lengthintegerThe maximum length of the input text
regexstringA regular expression the input text must match
formatstringA well known format, to facilitate being able to show useful prompts to the user.
Values: any, numerical, alphabetical, alphanumerical, email
{
  "some_input_id": {
    "type": "text",
    "display_text": "Some display text in English",
    "provider_description": "A message from the bank",
    "mandatory": true,
    "sensitive": false,
    "min_length": 5,
    "max_length": 15,
    "regex": "^[a-z ]{5,15}$",
    "format": "alphabetical"
  }
}
{
  "some_input_id": "entered value"
}

Text with image input

FieldTypeDescription
typestringValue indicating the field type: text_with_image
display_textstringText to describe what the field is asking for (English)
provider_description
(optional)
stringText directly from the bank relating to the field
mandatorybooleanIf the input must be provided
sensitivebooleanIf the input is sensitive (should be masked in UI)
min_lengthintegerThe minimum length of the input text
max_lengthintegerThe maximum length of the input text
regexstringA regular expression the input text must match
formatstringA well known format, to facilitate being able to show useful prompts to the user.
Values: any, numerical, alphabetical, alphanumerical, email
imageobjectAn image to display to the end user (for example, a QR code).
The image object can be of two types, base64 or uri.
If type is base64, there will be a base64 property containing the base64 data and media_type.
If type is uri, there will be a uri property with a URI to a hosted copy of the image.
{
  "some_input_id": {
    "type": "text_with_image",
    "display_text": "Some display text in English",
    "provider_description": "A message from the bank",
    "mandatory": true,
    "sensitive": false,
    "min_length": 5,
    "max_length": 15,
    "regex": "^[a-z ]{5,15}$",
    "format": "alphabetical",
    "image": {
      "type": "base64",
      "base64": {
        "data":
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8vlr6PwAHHAK+MKsa+gAAAABJRU5ErkJggg==",
        "media_type": "image/png"
      }
    }
  }
}
{
  "some_input_id": "entered value"
}

Select input

FieldTypeDescription
typestringValue indicating the field type: select
display_textstringText to describe what the field is asking for (English)
provider_description
(optional)
stringText directly from the bank relating to the field
mandatorybooleanIf the input must be provided
optionsSelectOption[]A list of id-display_text pairs to present to the end user as options (for example, a drop down).
{
  "some_input_id": {
    "type": "select",
    "display_text": "Some display text in English",
    "provider_description": "A message from the bank",
    "mandatory": true,
    "options": [
      {
        "id": "option-a",
        "display_text": "First Option"
      },
      {
        "id": "option-b",
        "display_text": "Second Option"
      }
    ]
  }
}
{
  "some_input_id": "option-b"
}

SelectOption

FieldTypeDescription
idstringValue to be provided on the initiation request, if the option is selected
display_textstringText to describe the option

Make a GET /providers call:

https://pay-api.truelayer.com/v2/single-immediate-payments-providers?client_id=myclient-123456&auth_flow_type=redirect,embedded&account_type=sort_code_account_number,iban&additional_input_type=text,select&currency=GBP,EUR

You get a response as below:

{
  "results": [
    {
      "provider_id": "ob-example",
      "logo_url": "https://truelayer-client-logos.s3-eu-west-1.amazonaws.com/banks/ob-example.svg",
      "display_name": "Example OB Bank",
      "country": "GB",
      "divisions": [ "retail", "business" ],
      "single_immediate_payment_schemes": [
        {
          "scheme_id": "faster_payments_service",
          "requirements": {
            "auth_flow": {
              "types": [ "redirect" ],
              "redirect": {
                "data_access_token_supported": true
              }
            },
            "single_immediate_payment": {
              "currency": {
                "supported_currencies": [ "GBP" ]
              },
              "beneficiary": {
                "account": {
                  "types": [ "sort_code_account_number" ],
                },
                "name": {
                  "mandatory": true,
                  "min_length": 1,
                  "max_length": 20,
                  "regex": "[\\w\\d ]{1,20}",
                  "format": "any"
                }
              },
              "remitter": {
                "mandatory": false,
                "account": {
                  "types": [ "sort_code_account_number" ],
                },
                "name": {
                  "mandatory": false,
                  "min_length": 1,
                  "max_length": 20,
                  "regex": "[\\w\\d ]{1,20}",
                  "format": "any"
                }
              },
              "references": {
                "types": [ "single", "separate" ],
                "single": {
                  "min_length": 1,
                  "max_length": 20,
                  "regex": "[\\w\\d \\.-]{1,20}",
                  "format": "any"
                },
                "separate": {
                  "beneficiary": {
                    "min_length": 1,
                    "max_length": 20,
                    "regex": "[\\w\\d \\.-]{1,20}",
                    "format": "any"
                  },
                  "remitter": {
                    "min_length": 1,
                    "max_length": 20,
                    "regex": "[\\w\\d \\.-]{1,20}",
                    "format": "any"
                  }
                }
              }
            }
          }
        }
      ]
    }
  ]
}

Use this response to create your provider selection screen.