Bank transfer payments

A single immediate payment is a one-time payment, executed in real-time.

In this section, we describe how you can:

Build a provider selection screen

To offer Open Banking payments to your users, you need a provider selection screen. Your users can select their bank from the screen to make the payment. You can build your own provider selection screen with /providers.

📘
We recommend you call the /providers endpoint every time you make a payment to make sure that you're always getting the latest information about providers.

The providers endpoint serves three purposes:

Tells you which banks are currently active (when a bank is temporarily unavailable, we hide them from this list until its service is restored).
Gives you the assets to build out a selection screen, for example, logos and display names.
Tells you 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:

Field	Available Values	Mandatory	Description
`client_id`	Your client ID	Mandatory	Required for verifying access to providers.
`auth_flow_type`	`redirect` `embedded`	Mandatory	Will only return providers with schemes that support the listed auth flows.
`account_type`	`sort_code_account_number` `iban` `bban` `nrb`	Mandatory	Will only return providers with schemes that support the listed account identifiers.
`currency`	ISO 4217 currency codes for example, `GBP,EUR`	Mandatory	Will only return providers with schemes that support the listed currencies.
`country`	ISO 3166-1 alpha-2 country codes for example, `GB,FR`	Optional	Will only return providers from the listed countries.
`additional_input_type`	`text` `select` `text_with_image`	Optional	Will 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_channel`	`live` `public_beta` `private_beta`	Optional	Will filter out any providers that are not on the specified release channel (`public_beta` also includes all those in `live`, and `private_beta` also includes all those in `public_beta`). If omitted, will only return providers that are generally available (equivalent to `live`).

Each bank available will have the following fields:

Field	Type	Description
`provider_id`	`string`	This is the provider ID that you will send us in the create payment request.
`logo_url`	`string`	This is the address of the logo asset in SVG form.
`icon_url`	`string`	This is the address of the icon asset in SVG form.
`display_name`	`string`	This is a readable name for the provider.
`country`	`string`	The ISO 3166-1 alpha-2 country code for the provider.
`divisions`	`string[]`	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_schemes`	`SingleImmediatePaymentScheme[]`	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.
`release_stage`	`string`	This 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

Field	Type	Description
`scheme_id`	`string`	A 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.
`requirements`	`SingleImmediatePaymentRequirements[]`	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.

• FeeOption

Field	Type	Description
`fee_option_id`	`string`	A 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_fee`	`string`	A value to indicate if the beneficiary would pay any fees on the transaction, when using this fee option. Values: `free`, `payable`, `unknown`
`remitter_fee`	`string`	A 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.

Field	Child Field	Type	Description
`auth_flow`	-	`AuthFlowRequirements`	Which auth flows are supported and what fields are required/available to initiate a payment for those flows.
`single_immediate_payment`	`currency`	`CurrencyRequirements`	Which currencies are supported.
`single_immediate_payment`	`beneficiary`	`ParticipantRequirements`	Which beneficiary details are required/supported.
`single_immediate_payment`	`remitter` (optional)	`ParticipantRequirements`	Which remitter details are required/supported. If omitted, the scheme does not support receiving remitter details.
`single_immediate_payment`	`references`	`ReferenceRequirements`	Which reference types are required/supported.

• AuthFlowRequirements

Field	Type	Description
`types`	`string[]`	A list of supported auth flow types. Values: `redirect`,`embedded`.
`redirect` (optional)	`RedirectAuthFlowRequirements`	Will be set if `redirect` is supported.
`embedded` (optional)	`EmbeddedAuthFlowRequirements`	Will be set if `embedded` is supported.

• RedirectAuthFlowRequirements

Field	Type	Description
`psu_ip_address_required` (optional)	boolean	Indicates if `auth_flow.psu_ip_address` is required on the initiation request.
`data_access_token_supported` (optional)	boolean	Indicates 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)	`AdditionalInputs`	An 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

Field	Type	Description
`additional_input_types`	`string[]`	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)	`AdditionalInputs`	An 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

Field	Type	Description
`supported_currencies`	`string[]`	A list of ISO 4217 currency codes supported by the provider scheme.

• ParticipantRequirements

Field	Child Field	Type	Description
`account`	`types`	`string[]`	A list of account types supported by the scheme. Values: `sort_code_account_number`, `iban`, `bban`, `nrb`.
`name` (optional)	-	`StringFieldRequirements`	An object detailing the requirements for the name, if omitted then setting the name on the initiation request is not supported for this scheme.
`mandatory`	-	bool	If a `remitter` is required. Not present on `beneficiary` as that is always mandatory.

• ReferenceRequirements

Field	Child Field	Type	Description
`types`	-	`string[]`	A list of supported reference types. Values: `single`,`separate`
`single` (optional)	-	`StringFieldRequirements`	Will be set if `single` is supported. Specifies the requirements for a single reference string for the payment.
`separate` (optional)	`beneficiary`	`StringFieldRequirements`	Will be set if `separate` is supported. Specifies the requirements for the beneficiary reference string for the payment.
`separate` (optional)	`remitter`	`StringFieldRequirements`	Will be set if `separate` is supported. Specifies the requirements for the remitter reference string for the payment.

• StringFieldRequirements

Field	Type	Requirement Description
`mandatory`	`boolean`	The corresponding field on the request is mandatory.
`min_length`	`integer`	The corresponding field on the request must be at least this many characters.
`max_length`	`integer`	The corresponding field on the request must be at most this many characters.
`regex`	`string`	The corresponding field on the request must match the regular expression.
`format`	`string`	A 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 Type	Description	Corresponding Request Value
`text`	Requires the end user to enter a string value	The string value the end user entered
`text_with_image`	Displays an image to the end user and requires them to enter a string value	The string value the end user entered
`select`	Provides a list of options for the end user to select from	The id of the selected option

• Text input

Field	Type	Description
`type`	`string`	Value indicating the field type: `text`
`display_text`	`string`	Text to describe what the field is asking for (English)
`provider_description` (optional)	`string`	Text directly from the bank relating to the field
`mandatory`	`boolean`	If the input must be provided
`sensitive`	`boolean`	If the input is sensitive (should be masked in UI)
`min_length`	`integer`	The minimum length of the input text
`max_length`	`integer`	The maximum length of the input text
`regex`	`string`	A regular expression the input text must match
`format`	`string`	A 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

Field	Type	Description
`type`	`string`	Value indicating the field type: `text_with_image`
`display_text`	`string`	Text to describe what the field is asking for (English)
`provider_description` (optional)	`string`	Text directly from the bank relating to the field
`mandatory`	`boolean`	If the input must be provided
`sensitive`	`boolean`	If the input is sensitive (should be masked in UI)
`min_length`	`integer`	The minimum length of the input text
`max_length`	`integer`	The maximum length of the input text
`regex`	`string`	A regular expression the input text must match
`format`	`string`	A well known format, to facilitate being able to show useful prompts to the user. Values: `any`, `numerical`, `alphabetical`, `alphanumerical`, `email`
`image`	`object`	An 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

Field	Type	Description
`type`	`string`	Value indicating the field type: `select`
`display_text`	`string`	Text to describe what the field is asking for (English)
`provider_description` (optional)	`string`	Text directly from the bank relating to the field
`mandatory`	`boolean`	If the input must be provided
`options`	`SelectOption[]`	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

Field	Type	Description
`id`	`string`	Value to be provided on the initiation request, if the option is selected
`display_text`	`string`	Text 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'll get a response like the following:

{
  "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 providers selection screen.

Get an access token

To get an access token, you'll need your client ID and client secret for the environment you are using (live or sandbox). The client ID can be found in the settings page of your Console. If you don't have your client_secret, you can also generate a new one.

Use our authentication server to get an access token using the client_credentials grant type. You'll need the access_token to make requests to different payments endpoints.

curl -X POST \
    -d grant_type=client_credentials \
    -d client_id=${client_id} \
    -d client_secret=${client_secret} \
    -d scope=payments \
    https://auth.truelayer.com/connect/token

{
  "access_token": "JWT-ACCESS-TOKEN-HERE",
  "expires_in": 3600,
  "token_type": "Bearer"
}