The direct API integration flow

The flow that you need to build for authorising a payment or mandate depends on whether:

1. You are accepting payments in the UK or EU
2. Your users need to select a banking provider or not
3. Your users need to select a payment scheme or not
4. Authorisation requires additional inputs from the user, such as an IBAN or a branch code
5. The bank account your user pays with requires a redirect, embedded or decoupled flow

📘

Simpler integration with TrueLayer UIs

Bypass the need to build logic for each of the above scenarios with the embedded payment page, hosted payment page or mobile SDKs.

1. UK vs EU payments

Payments into a EUR account must be made in EUR. Payments to a GBP account must be made in GBP.

Some payments in the EU have additional requirements, including additional inputs and different types of auth flow. Read the sections below for more information about these.

2. user_selected vs preselected providers

Most of the time, your user selects the provider they want to pay with on a provider selection screen. You must build a UI for this if you are integrating directly with our APIs.

📘

For guidance on building your own user interface to maximise adoption, conversion and retention, see our UX/UI guides.

But sometimes:

• your user has already paid you, and you have stored their preferred provider
• you only want to allow your user to pay via certain providers

In these two cases, you may want to preselect a provider for the user. This makes the experience smoother, which can increase conversion.

To specify whether you or the user selects a provider, set the value of provider_selection.type to preselected or user_selected in the payment creation request.

Below are two payment creation requests, one with the provider_selection object set to user_selected and one set to preselected.

{
    "amount_in_minor": 1,
    "currency": "GBP",
    "payment_method": {
        "type": "bank_transfer",
        "provider_selection": {
            "type": "user_selected"
        },
        "beneficiary": {
            "type": "merchant_account",
            "account_holder_name": "Merchant Account name",
            "merchant_account_id": "200552da-13da-43c5-a9ba-04ee1502ac57"
        }
    },
    "user": {
        "id": "cd101303-9124-4831-9fec-ef574ed22ecd",
        "name": "Test User",
        "email": "[email protected]",
        "phone": "+441234567890"
    }
}

{
    "amount_in_minor": 1,
    "currency": "EUR",
    "payment_method": {
        "type": "bank_transfer",
        "provider_selection": {
            "type": "preselected",
            "provider_id": "mock-payments-de-redirect",
            "scheme_id": "sepa_credit_transfer"
        },
        "beneficiary": {
            "type": "merchant_account",
            "account_holder_name": "Merchant Account name",
            "merchant_account_id": "2a485b0a-a29c-4aa2-bcef-b34d0f6f8d51"
        }
    },
    "user": {
        "id": "57e9ae89-01fd-4779-8775-5b7de9a85a64",
        "name": "Test user",
        "email": "[email protected]",
        "phone": "+441234567890"
    }
}

user_selected

In this flow, the user chooses which provider they want to pay with. Send your user to a provider selection UI, and allow them to choose a provider with a provider_selection action.

preselected

If you preselect a provider, you must supply a provider_id and scheme_id.

A payment can still have a provider selection type of preselected even if users select a provider through a provider selection screen. However, the user must select a provider before the payment and you must provide the provider_id at payment creation.

If a user has already paid you before, you can offer an option for them to pay with the same method they used previously. Then, you can create a preselected payment which uses the same provider_id as their previous payment.

3. Scheme selection

Some providers in the EU support multiple payment schemes. For example, SEPA Instant and SEPA Credit, which have different settlement speeds, and sometimes require fees.

If you provide a value of user_selected for provider_selection.scheme_selection.type when you create a payment, you need to send your user to a scheme selection UI. Here, you user should be able to select their preferred payment scheme.

You can enable scheme selection for payments that have either preselected or user selected provider selection.

You can also develop UI elements on the provider selection screen that enable users to filter providers by whether they support instant payments, or if a fee is required.

4. Additional inputs

Some providers in EU countries require the user to specify more details about the beneficiary. These details can include things such as:

• IBAN
• Branch
• Branch code
• Sub-account number

Ask the user to input these via a form action within the authorisation flow. For more on actions, see our page on authorisation flow actions.

For more information about which countries require additional inputs, see the page on additional inputs in the EU.

You can also store a user's IBAN and pass it at the payment creation stage, which can improve the user experience for payments in the EU. For more on this, read the page on storing and recalling a user's IBAN.

5. Authorisation flows

There are three types of payment authorisation flow which providers can support:

• redirect, where the user is redirected to their bank to authorise the payment
• embedded, where a bank's authorisation requirements are handled within your app or web page
• decoupled, where the user has to authorise the payment outside of your app or website

Most providers use redirect flows, but some in the EU use embedded or decoupled.