Select a provider for a payment

A bank_transfer cannot happen without a provider or bank to pay with. How you or your user chooses what provider to pay with depends on the value you choose for provider_selection when you create a payment. provider_selection is an object under the payment_method type bank_transfer.

There are two options to choose from for provider_selection:

1. user_selected
2. preselected

When you create a payment, in most circumstances the user chooses the PIS provider they want to pay with before they are redirected to their provider's website or app.

When you use user_selected, the flow looks like this:

When you use preselected, the flow is shortened like this:

We strongly recommend you use user_selected unless you have a specific reason to choose preselected instead. For example, if your user has already made a payment and you want to streamline the process for future payments, you might want to use preselected.

The providers you can create a payment with are limited to the banks in the region where the payment is made.

The user_selected provider selection method

A typical request body for a payment you create with user_selected as the provider_selection type is as below:

{
  "amount_in_minor": 100,
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected"
    },
    "beneficiary": {
      "type": "external_account",
      "account_holder_name": "Jane Doe",
      "reference": "some-reference",
      "account_identifier": {
        "type": "sort_code_account_number",
        "sort_code": "123456",
        "account_number": "12345678"
      }
    }
  },
  "user": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

When a payment is created with user_selected as the provider_selection type, two action types will become available during authorisation of the payment.

If you are using the hosted payment page, embedded payment page, iOS SDK or Android SDK to authorise the payment, these actions will be taken care of for you.

Filter provider_selection

You can filter which providers the user can select during payment authorisation.

A request body for the user_selected type with a filter looks like this:

{
  "amount_in_minor": 100,
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
      "filter": {
        "countries": ["GB"],
        "release_channel": "general_availability"
      }
    },
   .
   .
   .
}

🚧

We do not recommend that you use the countries or release_channel filters unless you have a specific use case in mind.

Countries

Limits your user's selection options to providers from the countries of your choice.

Currently you can set countries as GB, IE or FR. If left empty, the call includes all three countries.

For more information on the providers we support by country, see the Help Centre.

Release channel

The available release channels are:

• alpha
• private_beta
• public_beta
• general_availability

alpha includes all channels. private_beta includes channels in private and public beta and general availability, but not channels in alpha. public_beta includes only channels in public beta and general availability.

Scheme selection

When using the user_selected provider selection method, set the scheme_selection field to indicate which payment scheme will be used for the transaction.

An example provider and scheme selection looks like this:

"provider_selection": {
  "type": "user_selected",
  "filter": {
    "countries": ["FR"]
  },
  "scheme_selection": {
    "type": "instant_only",
    "allow_remitter_fee": true
  }
}
.
.
.

📘

Instant payments in the UK

Payments in the UK use Faster Payments (faster_payments_service), which is free and instant. If you only plan on making payments within the UK, you do not need to set scheme_selection for instant payments

Currently, there are two explicit options available. If you do not explicitly set this field, payments will use the default scheme for the respective currency (faster_payments_service for GBP and sepa_credit_transfer for EUR).

instant_only

If you use this type, we only return providers that support instant payments. Additionally, whatever provider the user chooses will use instant payments instead of any alternatives they support. Instant payments methods include faster_payments_service for GBP and sepa_credit_transfer_instant for EUR.

Many EU providers may charge the remitter a fee for using instant payments. These providers are not returned in the provider selection action by default. To include them, you can set the allow_remitter_fee flag to true.

🚧

Provider determined schemes

Some providers (e.g. Revolut) choose the payment scheme themselves. This is reflected in our API as the provider_determined scheme. Currently, we do not classify providers using provider_determined schemes as instant providers, as we cannot guarantee that the selected scheme will be instant. Hence, if you use the instant_only variant, these providers will not be included in the provider selection action.

instant_preferred

If you use this type, we only return providers that match the filters, regardless of whether they support instant payments or not, in the provider selection action. Once the user selects the provider, we will attempt to select an instant scheme if available. Otherwise, we will use the currency default scheme.

Many providers may charge the remitter a fee for using instant payments. By default, we will not select an instant scheme if this is the case. To allow instant schemes to be selected even if a remitter fee may be charged, set the allow_remitter_fee flag to true.

The preselected provider selection method

Using a preselected provider ensures that the payment is initiated with a specific provider that TrueLayer supports. You can retrieve these providers from one of our v2 endpoints. Learn more about payment providers and how to use the /providers endpoint.

remitter selection

A typical request body for a payment created with this provider_selection type will look like the following:

{
  "amount_in_minor": 100,
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "preselected",
      "provider_id": "ob-monzo",
      "scheme_id": "faster_payments_service"
    },
    "beneficiary": {
      "type": "external_account",
      "account_holder_name": "Jane Doe",
      "reference": "some-reference",
      "account_identifier": {
        "type": "sort_code_account_number",
        "sort_code": "123456",
        "account_number": "12345678"
      }
    }
  },
  "user": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

Choosing the type of provider_selection removes the provider_selection action from the user authorisation flow. The user will be redirected straight to a provider.

If you select preselected as the provider selection method, you can also preselect the remitter's payment details. This is useful if you want to ensure a payment comes from a specific account.

The format of the remitter object is the same as the beneficiary object. You need to provide an account_holder_name and an account_identifier of sort_code_account_number, iban, bban or nrb.

scheme_ids for payments

If you use the preselected provider selection method, you must provide a scheme_id and a provider_id to specify the payment scheme and provider.

The scheme_id field refers to the payment scheme a transaction uses. For example:

• Faster Payments in the UK
• SEPA Instant in Europe.

The values that you can select for the scheme_id field are below.

Learn how to check which schemes different providers support.