Authorise payments or mandates with the EPP
Learn how to set up the embedded payment page, create payments with it, and build callback functions.
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;
- 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
-
Import either the
Payment
or theMandate
component of the embedded payment page. -
Use the
payment_id
andresource_token
in the response from the Payments API, alongside your return URI, to initialise the embedded payment page. -
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. -
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')
},
})
Updated about 2 months ago