Create payments or mandates with the EPP

Follow the steps below to install the TrueLayer embedded payment page on your website and take your first payment, or set up your first variable recurring payment mandate.

Initial setup

  1. Install the embedded payment page into your app. You can use npm or yarn.
npm i truelayer-embedded-payment-page
# or 
yarn add truelayer-embedded-payment-page
  1. If you have one, add TrueLayer’s domains to your content security policy allow list.
frame-src 'self' https://payment.truelayer-sandbox.com;

frame-src 'self' https://payment.truelayer.com;
  1. Register your intended return URIs via Console.

Start a payment or mandate flow

  1. First, create the payment with the Payments API or create a payment mandate on the Payments API.

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

  3. Use 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 within a modal.

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 { Mandate } from 'truelayer-embedded-payment-page'

const mandate = Mandate({
  mandate_id: 'example-string',
  resource_token: 'example-string', 
  return_uri: 'example-string', 
})

mandate.start()

Provide 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 should reflect that the payment or mandate is processing, and you should wait for a webhook notification with the payment status.
  • onAbort the payment or mandate has been dismissed by the user.

Useful callback events

  • onLoad the iframe is loaded. (You may want to alter the rest of the page to ensure the user’s attention is focused at this point.)
  • onHandoffStart the user has used a QR code to transfer the flow to their mobile so they can authorise the payment or mandate with their bank app.
  • onError an error occurred that embedded payment page couldn’t handle. The error is passed to your function. An error message is also shown to the user.
// This example provides callback functions that log each callback event to the console

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

Confirm the payment result

After the user has successfully authorised their payment they are redirected to the return_uri that was specified when starting the payment or mandate flow.

In order to communicate the payment result to your user, you can retrieve the payment status via a webhook notification. See Receive webhook notifications for Payments v3 for more information.