Authorise payments or mandates 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

In order to use the embedded payment page, you first need to complete initial setup with NPM or Script.

Initial setup with 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;

2. Register your intended return URIs in Console. To do this, go to Console > Settings > App Settings.

Initial setup with 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/truelayer-embedded-payment-page@{version}/dist/truelayer-payment.min.js

https://unpkg.com/truelayer-embedded-payment-page@{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.

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. Optionally for payments (not mandates), include max_wait_for_result and include a value in seconds.
   This determines how long the EPP waits for a success result before it displays the payment result screen.
   If omitted, the EPP waits for 3 seconds. The maximum wait you can specify is 60 seconds, and the EPP treats a value over this as 60 seconds.

5. 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()

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

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

payment.start()

🚧

Avoid showing the EPP within your own modal

This can cause the window to respond incorrectly, which creates problems with the user experience.

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')
  },
})