The direct API integration flow

Users need to authorise payments (pay-ins) or VRP mandates made through the Payments API v3. TrueLayer offers a range of user interfaces for this, such as the hosted payment page, embedded payment page and mobile SDKs. These can handle authorisation for every type of payment the Payments API supports.

If you choose to integrate with the Payments API directly, you need to develop a user interface that can handle several factors. For example, rendering a screen for a user to select a banking provider, or to enter additional input such as a branch code or IBAN.

In a direct API integration, you provide this information through POST requests known as actions. When you start the authorisation flow, you receive a response that informs you what the next action is and contains the data you need to complete the next action. When you complete the action, you get another response that contains an action and the data you need to complete. You repeat this cycle until you receive the redirect or wait action, where the user authorises the payment with their banking provider. Learn more about actions.

There are five general factors that change the user interface your direct API integration needs to be able to handle:

1. The parameters you provide at payment or VRP mandate creation.
2. Whether the payment is in EUR or GBP.
3. If your user needs to select a banking provider and payment scheme.
   For returning payments, you can preselect this information for your users.
4. If the payment requires additional user input, such as a branch code.
5. If the banking provider requires a redirect, embedded, or decoupled authorisation flow.

Your payment authorisation flow must also inform your customer adequately, so they can give informed consent for TrueLayer to initiate payments or mandates from their bank account.

📘

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. Payment creation parameters

You determine the actions needed as part of the authorisation flow at payment creation. Specifically, the values you payment_method.provider_selection parameter determine if you need to complete the provider_selection or scheme_selection actions. Additionally, the currency parameter also impacts your user interface.

2. EUR vs GBP payments

Whether you select EUR or GBP as the currency at payment creation affects the currency that you should display to users as part of your payment authorisation user interface.

EUR payments can require additional user inputs, which need a user interface for users to enter. EUR payments can also need different authorisation flows such as embedded or decoupled flows. GBP payments doe not need additional user input, and always have the redirect authorisation flow.

3. Provider and scheme selection

The actions you need to complete to authorise a payment depend on the values you provide for the payment_method.provider_selection parameter when you create the payment.

It's possible to bypass the need to render a UI for provider selection and scheme selection by using preselected selection for them. However, you will still need some sort of UI outside of the authorisation flow in order to find out which banking provider your user wants to pay through.

Provider selection

Typically, you need to display a provider selection screen for users to select their banking provider. As part of your integration, you can develop logic for a search bar to filter providers, or use the availability object to inform users when a provider isn't currently available.

Scheme selection

For EUR payments, you can also display a scheme selection screen, so users can choose whether to pay via a SEPA credit instant transfer, or slower SEPA credit transfer.

Some banking providers charge fees for instant payments, so your UI should inform your users of this if relevant.

Returning payment user flow

If a user is returning to your app to make an additional payment, we recommend that you provide an option for them to pay with the same details they've used previously.

To do this, you should develop a logic that stores the provider_id and scheme_id your user selects in their initial payment.

When your user creates a second payment through your website or app, offer them an option to pay with their saved details, or something to that effect. Then, you can choose the preselected method for both the provider and scheme selection parameters at payment creation. This removes the need to render a provide or scheme selection screen in the payment authorisation flow, improving the user experience.

In this case, you should provide a value of preselected for the payment_method.provider_selection.type and payment_method.provider_selection.scheme_selection.type parameters at payment creation. If you do this and provide the provider_id and scheme_id from the user's previous payment, you can remove the provider and scheme selection screens from your payment authorisation user interface. This simplifies the payment process and increases customer satisfaction.

4. Additional user inputs

When a user makes a payment in the EUR currency, some providers require the user to submit additional information such as a branch code, or their IBAN.

Your user interface should provide be able to render a screen, or series of screens, that enable the user to provide this information. If you plan to receive EUR payments, your integration needs to be able to render three types of screen for additional user input:

• A screen that contain text fields for users to enter information.
• A screen that contain an image and text fields for users to enter information.
• A screen where users can select a value from a list.

5. User authorisation flow

There are several different flows for how the user authorises the payment at the end of your flow. The most common is the redirect flow, where the user is redirected from your app or website to their bank's to authorise the payment.

Certain banks, typically in France or Germany require embedded or decoupled flows. In an embedded flow, your user provides information to their bank, such as username or password through fields you render in your authorisation user interface. In a decoupled flow, your user completes a task outside of your flow, such as within an authenticator app – your user interface should display relevant information during this process.

User consent requirements

If you are not regulated for payment initiation services under PSD2 in the UK or EU, then you must display some additional information in your journey. This additional information ensures that your user understands and consents to TrueLayer initiating a payment from their bank account.

Learn more about the information you need to include in your flow for either payments or VRP mandates.