Select a scheme for payments

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:

Name	`scheme_selection.type` in payment request	Region	Instant/non-instant
Faster Payments Service	`faster_payments_service`	UK	Instant
SEPA Instant	`sepa_credit_transfer_instant`	EU	Instant
SEPA Credit	`sepa_credit_transfer`	EU	Non-instant
Provider determined	`provider_determined`	N/A	Non-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 method	`user_selected` provider selection behaviour	`preselected` provider selection behaviour
`instant_only`	The 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_preferred`	The 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_selected`	The 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.
`preselected`	You 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

The "provider_determined" payment scheme in the UK

In the UK, all payments are made over the Faster Payments scheme, which is instant. However, some banking providers, such as Wise, 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 won't display these banks as supporting instant_only.

This is typically 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 those providers display on the provider selection screen.

"payment_method": {
  "provider_selection": {
    "scheme_selection": {
      "type": "instant_preferred"
    },
    "type": "user_selected"
  },
},

Revolut UK exception

When you get information about providers, Revolut in the UK is returned with the scheme_id of provider_determined:

{
  "id": "ob-revolut",
  ...
        "schemes": [
          {
            "id": "provider_determined",
          }
        ]
        ...
},

Hence, using the scheme_selection.type as shown above, Revolut is returned and supported in the UK.

However, Revolut (ob-revolut) is also returned when you restrict provider_selection to instant_only by changing the scheme_selection type.

"payment_method": {
    ...
    "provider_selection": {
      "scheme_selection": {
        "type": "instant_only"
      },
      "type": "user_selected"
    },
    ...
  },

This means that, if you set provider_selection and scheme_selection to preselected, you can use the provider_determined scheme_id for Revolut:

"payment_method": {
    "provider_selection": {
      "type": "preselected",
      "provider_id": "ob-revolut",
      "scheme_selection": {
        "type": "preselected",
        "scheme_id": "provider_determined"
      }
      ...
    }
  },

But you can also use the faster_payments_service scheme_id:

"payment_method": {
    "provider_selection": {
      "type": "preselected",
      "provider_id": "ob-revolut",
      "scheme_selection": {
        "type": "preselected",
        "scheme_id": "faster_payments_service"
      }
      ...
    }
  },

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
}

Force specific providers to use a specific scheme

You may find it useful to enable payments over only SEPA Instant or SEPA Credit for a specific provider or list of providers.

To do this, add the list of provider IDs that you want to enable for SEPA Instant only to the instant_override_provider_ids field. If you want to enable some providers for SEPA Credit only, add their IDs to the non_instant_override_provider_ids field.

If you use this feature, the providers will disregard any settings in the allow_remitter_fee field.

Below is an example of a payment request with example provider IDs for instant and non-instant payment schemes:

{
"amount_in_minor": 1,
"currency": "GBP",
"payment_method": {
  "type": "bank_transfer",
  "provider_selection": {
    "type": "user_selected",
    "filter": {
       "countries": [
          "GB"
       ],
       "release_channel": "general_availability",
       "customer_segments": [
          "retail"
       ],
       "provider_ids": [
          "mock-payments-gb-redirect"
       ],
       "excludes": {
         "provider_ids": [
           "ob-exclude-this-bank"
         ]
       }
    },
    "scheme_selection": {
      "type": "instant_only",
      "allow_remitter_fee": false,
      "instant_override_provider_ids": [
        "example-provider-id-instant"
      ],
      "non_instant_override_provider_ids": [
        "example-provider-id-non-instant"
      ]
   }
},