Create 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

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;

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

First, create the payment with the Payments API from your backend.
Import either the Payment or the Mandate component of the embedded payment page.
Use the payment_id and resource_token in the response from the Payments API, alongside your return URI, to initialise the embedded payment page.
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')
  },
})