Provider selection for new and returning users

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.

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 types you can specify within the provider_selection object: user_selected or preselected. The format of your payment creation request changes based on the type of provider selection you use.

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 first-time user flow

For first-time users, it is usually best to use user_selected provider selection. (There are exceptions to this: see Preselected payments for first-time users to learn more.)

In 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 .

user_selected provider selection

Adjusting the parameters inside the provider_selection object enables you to display a filtered list of providers for the user to select from, and adjust the options to their local market. 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:

The release_channel filter for providers

Whether 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.

The customer_segments filter for providers

When 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.

The returning user flow

After a user has paid you for the first time, you can change values of the provider_selection and remitter objects to supply information you already know about the payment provider being used in the first payment. You can find information about these in the webhooks you receive after a payment has reached the executed or settled status. This can greatly improve the returning user experience.

This guide includes information about how to do this.

{To enable the returning user flow, you must also fill out the user object in the initial payment.}

preselected provider selection

In a payment with a preselected type under the provider_selection object, you specify the provider the payment is made through, using the provider_id field. This implied you need to know which provider the user will pay with. Typically, this is because you have stored their preference after a previous payment.

We recommend that you use preselected provider selection for users who are known to you because they've paid you before. When the user creates their first payment, you can store their preferred banking provider and use it to remove the need for provider selection in subsequent payments. You can also store their banking details and prefill the remitter parameter to simplify account selection in future payments.

This is the format of a payment with preselected 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": 1000,
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "preselected",
      "provider_id": "mock-payments-gb-redirect",
      "scheme_selection": {
    "type": "instant_preferred"
    },
      "remitter": {
        "account_identifier": {
          "type": "sort_code_account_number",
          "sort_code": "123456",
          "account_number": "12345678"
        },
        "account_holder_name": "Optional Remitter"
      }
    },
    "beneficiary": {
      "type": "merchant_account",
      "account_holder_name": "Merchant Account name",
      "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57",
      "reference": "testRef 001"
    }
  },
  "metadata": {
    "newKey": "New Value 001 test"
  },
  "user": {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
    "name": "Jonathan Sandbridge",
    "email": "[email protected]",
    "phone": "+44123456789",
    "date_of_birth": "1992-11-28",
    "address": {
      "address_line1": "40 Finsbury Square",
      "city": "London",
      "state": "London",
      "zip": "EC2A 1PX",
      "country_code": "GB"
    }
  }
}

In a preselected payment, you need to specify the provider_id within the provider_selection parameter. This example specifies the mock-payments-gb-redirect sandbox provider.

A key use case for the preselected provider selection type is to simplify the authorisation flow when you know a user's preferred provider. When you set the type to preselected, you can skip provider selection screens.

To get information about a user's preferred provider and account, you can store the information you receive from the executed or settled webhooks to fill out the provider_selection object when they pay you again.

📘

Web SDK

The Web SDK has specific behaviours for automatically detecting returning users, using data from the user object. For more on this, see the web SDK docs.

Store information from payment status webhooks

A payment_executed and payment_settled webhook look like this:

{
  "type": "payment_settled",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payment_id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "payment_method": {
    "type": "bank_transfer",
    "provider_id": "mock-payments-de-redirect",
    "scheme_id": "sepa_credit_transfer"
  },
  "settled_at": "2021-12-25T15:00:00.000Z",
  "payment_source": {
    "account_identifiers": [
      {
        "type": "iban",
        "iban": "DE79370400440532013000"
      }
    ],
    "id": "1f111d3c-9427-43be-1111-1111219d111c",
    "account_holder_name": "HOLDER NAME"
  },
  "user_id": "ec01ece1-1dbe-48f1-82b2-bce8cfa44d08"
}

{
  "type": "payment_executed",
  "event_version": 1,
  "event_id": "b8d4dda0-ff2c-4d77-a6da-4615e4bad941",
  "payment_id": "60c0a60ed8d7-4e5b-ac79-401b1d8a8633",
  "executed_at": "2021-12-25T15:00:00.000Z",
  "payment_method": {
    "type": "bank_transfer",
    "provider_id": "mock-payments-gb-redirect",
    "scheme_id": "faster_payments_service"
  },
  "payment_source": {
    "account_identifiers": [
      {
        "type": "sort_code_account_number",
        "sort_code": "040668",
        "account_number": "00000871"
      }
    ],
    "account_holder_name": "JOHN SANDBRIDGE"
  }
}

Below is a guide to the fields you would use to populate a subsequent payment by an end user.

The remitter object

You can also fill out the user's account details in the remitter object, if you know in advance the specific account that they want to pay with. This simplifies the journey by preselecting the bank account for the user when they authorise a payment with their banking provider. This means that, for example, they don't have to choose between their personal or joint account.

The remitter object contains:

• account_holder_name, which is the name associated with the payee's bank account
• account_identifier, which includes their bank account details.

The account_identifier object includes a type field. Set the type to sort_code_account_number for GBP payments, and iban for EUR payments.

Your integration must be able to identify which currency a payment is made in. This is because the payment_settled webhook for GBP payments includes both an IBAN and SCAN, but for GBP payments only SCAN works with the remitter object.

This code block contains examples of what the remitter parameter looks like for SCAN and IBAN accounts:

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": {
    "provider_selection": {
    "type": "preselected",
    "provider_id": "mock-payments-gb-redirect",
    "scheme_selection": {
    "type": "user_selected"
    },
      "remitter": {
        "account_holder_name": "John Sandbridge",
        "account_identifier": {
          "type": "sort_code_account_number",
          "sort_code": "500000",
          "account_number": "12345601"
        }
      }
  },
    "type": "bank_transfer",
    "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"
    }
  }
}

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": 1000,
  "currency": "EUR",
  "payment_method": {
    "provider_selection": {
    "type": "user_selected",
    "scheme_selection": {
    "type": "user_selected"
    },
      "remitter": {
        "account_holder_name": "John Sandbridge",
        "account_identifier": {
          "type": "iban",
          "iban": "DE78740201006814567316"
        }
      }
  },
    "type": "bank_transfer",
    "beneficiary": {
      "type": "merchant_account",
      "merchant_account_id": "2a485b0a-a29c-4aa2-bcef-b34d0f6f8d51"
    }
  },
  "user":
  {
    "id": "f61c0ec7-0f83-414e-8e5f-aace86e0ed35",
    "name": "Jonathan Sandbridge",
    "email": "[email protected]",
    "phone": "+44123456789",
    "date_of_birth": "1992-11-28",
    "address":
    {
      "address_line1": "1, Hardwick Street",
      "city": "London",
      "state": "London",
      "zip": "EC1R 4RB",
      "country_code": "GB"
    }
  }
}

In the example below:

• the left column is the settled webhook that follows a first-time payment
• the right column is the subsequent payment, which now has a provider_selection type of preselected.
  The payment request also includes the remitter object.

The arrows indicate where to pass the information from the webhook in a subsequent payment request.

🚧

Some European banks outside of the UK, France, and Ireland require that you provide the user's IBAN, otherwise they fail.

To find out if a providers requires an IBAN for a preselected payment, see if iban is included in this object in the response from the /v3/payment-providers/search endpoint:

capabilities.payments.bank_transfer.schemes.requirements.account_identifier_types

preselected payments for first-time users

There are use cases where you may want to use a provider_selection:type of preselected even for new users:

• Where you use the Data or Verification APIs to fetch information about your user before they pay you
• Where you build your own provider selection screen, and then initiate a new payment with your customer's selection afterwards

Sandbox banking providers

If you want to test how provider selection or payment authorisation works in our sandbox environment, we offer a range of sandbox providers you can use. Learn more about sandbox providers and how to test payments in the sandbox environment.

How bank downtime displays

Sometimes, a bank is unavailable. This can be due to planned downtime, or an outage.

If you use a TrueLayer authorisation UI, it automatically detects if a bank is unavailable and greys out that bank's logo. This gives your user a chance to select a different bank. If you build your own UI, the provider selection response contains the information and assets you need to develop this functionality yourself.

The sandbox environment contains an example of a 'healthy' and 'unhealthy' provider, with these provider IDs:

• mock-payments-gb-redirect
• mock-payments-gb-redirect-unhealthy

You can use these providers to test how bank downtime displays in your authorisation flow.

If you want to be notified when a bank is experiencing or has planned downtime, you can subscribe to receive email alerts from TrueLayer here.