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 withuser_selected
, which enables your user to choose their schemeinstant_only
, which specifies that the payment must be made throughinstant_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"
]
}
},
Updated 15 days ago