Provider selection for first-time 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.

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

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 .

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:

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.