Use the single-immediate-payments-providers endpoint [Payments V2]
Learn how to return a list of banking providers through an endpoint.
The information returned by the
/v2/single-immediate-payments-providers
endpoint is still accurate and can be used with the Payments API v3.However, we recommend you use the more recent
/v3/payment-providers/search
endpoint for all new integrations.
If you want to return a list of providers and the id
for each of them, you can make a GET request to the /v2/single-immediate-payments-providers
endpoint.
Configuring the endpoint
There are four things to consider when you use the /single-immediate-payments-providers
endpoint.
Remitter details for EU banks
Some European banks outside of the UK, Ireland, and France may require remitter details. To use these providers, you need to collect the remitter's account details. If you don't collect these details, the payment fails.
Provide the remitter's account details in the payment_method.provider_selection.remitter
object (which only displays if you use preselected
as the provider selection method).
To see if a provider needs remitter account details, check the response of the /single-immediate-payments-providers
endpoint. If they are required, the value of the following Boolean parameter in the response is true
:
results.single_immediate_payment_schemes.requirements.single_immediate_payment.remitter.mandatory
Possible authorisation flow types
Most integrations use redirect
as the value for the auth_flow_type
object. However, you can also use embedded
to return providers that use an embedded authorisation flow.
Payment schemes
The /single-immediate-payments-providers
endpoint returns the payment schemes that a provider supports. The supported payment rails are returned as scheme_id
in the results.single_immediate_payment_schemes
object. Each payment rail is represented by a scheme_id
.
The faster_payments_service
and sepa_credit_transfer_instant
payment rails are considered instant, as payments on them settle within seconds or minutes. The sepa_credit_transfer
payment rail isn't considered instant, as payments on it take 1-3 days to settle.
Provider availability
The payments API returns the availability of each provider whenever you:
- make a request to the
/single-immediate-payments-providers
endpoint - start an auth flow for a
user_selected
payment
This information is returned in the availability
object, which contains three objects, explained below.
Name of object | Meaning |
---|---|
recommended_status | Can either have a value of healthy or unhealthy . These mean that a provider is available or unavailable respectively. |
error_rate | A ratio that shows the ratio above which a provider is considered healthy. This changes based on the provider. |
updated_at | When the provider's availability was checked, as a RFC-3339 timestamp. |
When you create a payment, you can choose four different options for how the scheme is selected. Select the options by providing the scheme selection method in the payment_method.scheme_selection.type
object.
For more information about scheme selection, see [Select a payments scheme for payments].
What the /single-immediate-payments-providers
endpoint returns
/single-immediate-payments-providers
endpoint returnsUse the v2 /single-immediate-payments-providers
endpoint to retrieve a list of providers for payments. This list also includes the following information:
- a
provider_id
for the provider - provider logos with URLs
- the country the provider is in
- information about applicable payment fees
- the available authorisation methods
- a list of the payments rails supported by the provider
- the current availability of the provider with an error rate
/single-immediate-payments-providers
can be useful when you are creating a customised integration, using thepreselected
provider selection method to select a provider.However, if you are integrating for a standard use case with the
user_selected
provider selection method, we recommend that you do not use the/single-immediate-payments-providers
endpoint.
We provide provider logos in SVG format to maximise quality and scalability.
Example /single-immediate-payments-providers
response
/single-immediate-payments-providers
responseThis is an example of the response that the v2 /single-immediate-payments-providers
endpoint returns:
{
"results": [
{
"provider_id": "ob-revolut",
"logo_url": "https://truelayer-provider-assets.s3.amazonaws.com/global/logos/revolut.svg",
"icon_url": "https://truelayer-provider-assets.s3.amazonaws.com/global/icons/revolut.svg",
"display_name": "Revolut",
"country": "GB",
"divisions": [
"retail"
],
"single_immediate_payment_schemes": [
{
"scheme_id": "faster_payments_service",
"fee_options": [
{
"fee_option_id": "string",
"beneficiary_fee": "free",
"remitter_fee": "free"
}
],
"requirements": "(Omitted from this example)"
}
],
"availability": {
"recommended_status": "healthy",
"error_rate": 0.5,
"updated_at": "2023-05-24T13:35:19.883Z"
}
}
]
}
Updated 7 months ago