Customise the EPP user flow

Page presentation

By default, the embedded payment page is presented as a modal, overlaid on top of your web page. However, you can also choose to display EPP inline on your page, sitting next to your other web content.

2224

To display EPP inline in your page instead, you can configure it to load it inside your own web page element. To do this, set the target field when you import the embedded payment page.

When the flow is finished (indicated by the onAbort or onDone callbacks), remember to unmount EPP from the DOM.

import { Payment } from "truelayer-embedded-payment-page";

const payment = Payment({
  payment_id: "your-payment-id",
  return_uri: "your-return-uri",
  resource_token: "your-resource-token",
  // mount the embedded payment page in the target element
  target: document.getElementById("your-target-id")!,
  // remove the target element from the DOM after the payment is done
  onDone: () => {
    const target = document.getElementById("your-target-id");
    if (target) {
      target.remove();
    }
  },
  // remove the target element from the DOM if the user aborts the payment
  onAbort: () => {
    const target = document.getElementById("your-target-id");
    if (target) {
      target.remove();
    }
  },
});

👍

Ensure your user can see the payment correctly by setting your target node to at least 320px by 320px in size.

Country selection

The currency of a payment defines which countries a user can pick to pay from. So for a payment in euros, there's a range of countries that the user can choose between. To help simplify that choice, EPP will pick a default country based on the browser locale, but allows the user to switch to a different country if needed.

You can control which countries your user can choose from, by setting a provider filter when you create the payment with the Payments API.

Bank selection

On the selection screen, banks are sorted by the highest market share first.

Banks are also assigned a release channel based on the maturity level of our integration. You can choose whether or not you want to include those that are in a beta release channel by using the provider filter when you create the payment with the Payments API.

Language

EPP selects the best language to display the user interface in, based on the browser locale. It supports the following languages:

  • English
  • Spanish
  • French
  • German
  • Dutch
  • Portuguese
  • Polish
  • Finnish
  • Lithuanian

If you need to, you can override the automatic language selection by specifying the language property using the ISO Alpha-2 code format:

const payment = Payment({
  ...,
  language: 'fr'
})

Signup+

If the payment is part of a Signup+ onboarding flow, then you may want to use EPP to explain the additional data collected, and how it's used. If you set the Signup+ option to true when you start the payment flow, then the Review Payment screen shows an additional message.

2812

Here's how to enable the Signup+ message.

import { Payment } from 'truelayer-embedded-payment-page'
const payment = Payment({
  payment_id: 'example-string',
  resource_token: 'example-string',
  return_uri: 'example-string',
  signup: true,
})
payment.start()

Additional inputs

Some banks outside the UK require us to provide additional information about the paying user in order to initiate the payment. That can include their branch or their IBAN. When necessary, The EPP asks the user to enter these details. A limited number of banks also require that the user log in to their bank account through the EPP screen, which it also handles securely.

1996

Entering their IBAN can be a source of friction for your users, but you can simplify this process. If you already have a record of your user's IBAN, then you can provide it to the Payments API when you create the payment in order to prevent the user from being asked to enter it as part of the payment. This is done using the preselected type of provider_selection. See Provider Selection for more information.

Bank redirects

In most cases, users get redirected to their bank to authorise the payment. There are some options for how this redirect works.

QR codes

For many banks, the authorisation experience is much easier from the bank's mobile app. In these cases, EPP automatically opens the app if the user is on their phone, or otherwise falls back to the website if they don't have the app installed. If the user is paying from a laptop, then EPP displays a QR code that the user can scan to launch the payment authorisation in their bank app, or else they can choose to continue to the bank's website on their laptop.

2362

Redirecting in a new tab

For those cases where the user is taken to the bank's website, you can choose where to load the bank's page. By default, the bank page is loaded in the current browser tab. That is, the bank's page replaces your page, so neither your page nor EPP is visible any longer. Once they've authorised (or cancelled) the payment, then the user is returned to your website using the return URI that you set at the start of the payment flow.

As an alternative, you can choose to open a new tab for the bank page, so your page and the EPP are still available for the user to switch back to. Once the user has authorised (or cancelled) the payment, then the second tab is automatically closed and the user returns to your page. You can configure your site to react to the user returning, using the same onDone and onAbort callback events.

import { Payment } from 'truelayer-embedded-payment-page'
const payment = Payment({
  payment_id: 'example-string',
  resource_token: 'example-string',
  return_uri: 'example-string',
  openBankInTab: true,
})
payment.start()