Select a scheme for payments

Payments must travel along payments rails. Select which schemes you want to enable users to pay with.

Just as you can enable your user to select a banking provider or preselect it for them, you can do the same for payment schemes.

There are a variety of scheme selection logics you can specify within the scheme_selection object:

  • preselected, which enables you to set the scheme your user will pay with
  • user_selected, which enables your user to choose their scheme
  • instant_only, which specifies that the payment must be made through
  • instant_preferred, which defaults to instant payments unless none are available

Available schemes

These are the schemes that you can select from, if you choose to preselect a scheme for your user:

Namescheme_selection.type in payment requestRegionInstant/non-instant
Faster Payments Servicefaster_payments_serviceUKInstant
SEPA Instantsepa_credit_transfer_instantEUInstant
SEPA Creditsepa_credit_transferEUNon-instant
Provider determinedprovider_determinedN/ANon-instant

All banks in the UK use the Faster Payments Service. These payments are free and usually settle in the beneficiary account within seconds, so it's considered an instant scheme (although can take up to 2 hours).

When you make a payment in Europe, the payment can use the non-instant but cheaper Sepa Credit scheme, or the instant Sepa Instant scheme, for which banks sometimes charge a fee.

Learn more about the differences between schemes for payments in Europe.

Some banks also support provider_determined as an option. This is used by some providers who choose the payment scheme themselves when the user pays. We cannot guarantee that payments are instant when you use provider_determined for the scheme_id, so providers that use it are treated as non-instant when you specify this for scheme selection.

If you are using the user_selected option, include a UI which allows your user to choose the scheme. The hosted payment page, embedded payment page, and mobile and React SDKs handle this for you automatically.

Scheme selection interactions with provider selection

The behaviour of your scheme_selection method differs based on the provider_selection you choose. This is an overview of the different available combinations:

Scheme selection methoduser_selected provider selection behaviourpreselected provider selection behaviour
instant_onlyThe provider selection screen only displays providers that support instant payment schemes. The user cannot select a non-instant scheme.

If the payment fails over the instant payment scheme, instant_only ensures it doesn't fall back to a non-instant scheme.
If the preselected provider supports both instant and non-instant payment schemes, instant_only ensures that the payment will not fall back to a non-instant scheme if it fails.
instant_preferredThe provider selection screen displays providers that support both instant and non-instant payments schemes.

If the instant payment fails, instant_preferred ensures it falls back to a non-instant scheme.

We recommend you use instant_preferred for all UK payments.
If the preselected provider supports both instant and non-instant payment schemes, the payment will not fall back to a non-instant scheme if the instant payment fails.

If you choose preselected and instant_preferred and also specify allow_remitter_fee as false, the payment uses a non-instant scheme if there is a fee for the instant scheme.

We recommend you use instant_preferred for all UK payments.
user_selectedThe provider selection screen displays all providers, regardless of whether they support instant or non-instant payment schemes, or both.

After they select a provider, the user sees a screen where they can select between an instant or non-instant payment scheme (if the provider supports both).
A scheme selection screen displays, but a provider selection screen does not.

The user sees a screen where they can select between an instant or non-instant payment scheme (if the provider supports both). This does not display if the provider only supports one type of scheme.
preselectedYou cannot use preselected scheme selection with user selected provider selection.With preselected provider and scheme selection, neither a provider or scheme selection screen displays.

We recommend you use this combination for returning users who have saved their preferred provider and payment scheme.

If you don't specify a scheme selection method at payment creation, the payment uses the default scheme for each currency:

  • Faster Payments for GBP
  • SEPA Credit for EUR

🚧

Use instant_preferred for UK payments

In the UK, all payments are made over the Faster Payments scheme, which is instant. However, some banking providers, such as Revolut, determine the payment scheme themselves. This is usually instant, but as we can't guarantee the payment will be made over an instant scheme, we don't display these banks as supporting instant_only.

As such, you should use instant_preferred as the scheme selection for UK payments to ensure that providers such as Revolut display on the provider selection screen.

This behaviour results from a scheme known as provider_determined, which was used in this scenario for the deprecated scheme_id parameter when you create a payment.

Disallow remitter fees

Some payments, usually instant payments, cost additional fees.

To filter out providers that charge fees, set allow_remitter_fee to false.

Below is an example of a full payment request, with user_selected provider selection and instant_only scheme selection:

{
  "currency": "EUR",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "user_selected",
      "filter": {
        "release_channel": "general_availability",
        "customer_segments": [
          "retail"
        ]
      },
      "scheme_selection": {
        "type": "instant_only",
        "allow_remitter_fee": false
      }
    },
    "beneficiary": {
      "type": "merchant_account",
      "verification": {
        "type": "automated"
      }
    }
  },
  "amount_in_minor": 100
}

Select a scheme with the scheme.id method

For a payment with preselected provider selection, you can provide a scheme.id within the provider_selection object, if you want your user to pay with a specific scheme.

🚧

We don't recommend that you select a scheme with this method, as the scheme_selection method is more flexible and reliable.

If you need to preselect a payment scheme, we recommend you use the scheme_selection method with a type of preselected instead.

Below is an example of a payment request with no scheme_selection object, but a scheme.id set within the provider_selection object.

{
  "currency": "GBP",
  "payment_method": {
    "type": "bank_transfer",
    "provider_selection": {
      "type": "preselected",
      "filter": {
        "release_channel": "general_availability",
        "customer_segments": [
          "retail"
        ]
      },
      "scheme_id": "faster_payments_service",
      "provider_id": "eg-provider"
    },