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
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:
- The parameters you provide at payment or VRP mandate creation.
- Whether the payment is in EUR or GBP.
- If your user needs to select a banking provider and payment scheme.
For returning payments, you can preselect this information for your users.
- If the payment requires additional user input, such as a branch code.
- If the banking provider requires a redirect, embedded, or decoupled authorisation flow.
Simpler integration with TrueLayer UIs
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
scheme_selection actions. Additionally, the
currency parameter also impacts your user interface.
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.
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.
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.
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.
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
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.scheme_selection.type parameters at payment creation. If you do this and provide the
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.
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.
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.
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.
Updated about 1 month ago