Payments or mandates with the EPP

Set up the embedded payment page.

The embedded payment page (EPP) uses a prebuilt user interface to speed up the integration process.

  • It's embedded into your web page, as an overlay or inline on your page
  • It has a customisable user interface, so you can adapt the style to best fit your page
  • QR code authentication allows desktop users to authorise payments with their mobile banking app
  • It has built-in localisation, covering local languages and authentication flows for a range of European countries

The embedded payment page supports:

Create a payment or mandate with the EPP

The following steps show you how to install the TrueLayer embedded payment page on your website and take your first payment.

Initial setup

NPM

npm i truelayer-embedded-payment-page
yarn add truelayer-embedded-payment-page
  1. If you have one, add TrueLayer’s domains to your content security policy allowlist.
frame-src 'self' https://payment.truelayer-sandbox.com;

frame-src 'self' https://payment.truelayer.com;
  1. Register your intended return URIs in Console. To do this, go to Console > Settings > App Settings.

Script

https://cdn.jsdelivr.net/npm/truelayer-embedded-payment-page/dist/truelayer-payment.min.js
https://unpkg.com/truelayer-embedded-payment-page/dist/truelayer-payment.min.js

These script links will fetch the latest version of the truelayer-embedded-payment-page if you require a specific version you can use the following links:

https://cdn.jsdelivr.net/npm/[email protected]{version}/dist/truelayer-payment.min.js
https://unpkg.com/[email protected]{version}/dist/truelayer-payment.min.js

Where {version} corresponds to a version which can be found here.

Start a payment

  1. First, create the payment with the Payments API from your backend.

  2. Import either the Payment or the Mandate component of the embedded payment page.

  3. Use the payment_id and resource_token in the response from the Payments API, alongside your return URI, to initialise the embedded payment page.

  4. You can then start the payment or mandate flow. This opens the user interface on your page as an iframe.

import { Payment } from 'truelayer-embedded-payment-page'

const payment = Payment({
  payment_id: 'example-string', 
  resource_token: 'example-string',
  return_uri: 'example-string',
})

payment.start()

Build callback functions

The embedded payment page returns callback events. Use these to develop callback functions so your web page can respond to key events in the payment process.

Essential callback events

  • onDone the flow of the embedded payment page is done. Your page must reflect that the payment is processing. Wait for a webhook notification with the payment status.
  • onAbort the payment has been dismissed by the user.
  • onError an error occurred that the EPP couldn’t handle. The error is passed to your function.

Useful callback events

  • onLoad the iframe is loaded. (You may want to change the rest of the page to grab the user’s attention at this point.)
  • onHandoffStart the customer has used a QR code to continue with their mobile bank app.
// This example provides callback functions that log each callback event to the console

const payment = window.Truelayer.Payment({
  payment_id: 'example-string',
  resource_token: 'example-string',
  return_uri: 'example-string',
  onLoad: () => {
    console.log('onLoad called')
  },
  onHandoffStart: () => {
    console.log('onHandoffStart called')
  },
  onAbort: () => {
    console.log('onAbort called')
  },
  onError: error => {
    console.log('onError called', error)
  },
  onDone: () => {
    console.log('onDone called')
  },
})
// This example provides callback functions that log each callback event to the console

const mandate = Mandate({
  mandate_id: 'example-string',
  resource_token: 'example-string',
  return_uri: 'example-string',
  onLoad: () => {
    console.log('onLoad called')
  },
  onHandoffStart: () => {
    console.log('onHandoffStart called')
  },
  onAbort: () => {
    console.log('onAbort called')
  },
  onError: error => {
    console.log('onError called', error)
  },
  onDone: () => {
    console.log('onDone called')
  },
})