Embedded Payments Page - EPP

Accept payments using TrueLayer's Hosted Payments Page directly on your website.

Disclaimer

The EPP is in private beta so although we strive to keep all the APIs / SDKs unchanged and interrupted, we may occasionally issue breaking changes into features.

Installation

NPM

npm i truelayer-embedded-payment-page
# or
yarn add truelayer-embedded-payment-page
# or
pnpm add truelayer-embedded-payment-page

Script tag

https://cdn.jsdelivr.net/npm/truelayer-embedded-payment-page/dist/truelayer-payment.min.js
or
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://unpkg.com/truelayer-embedded-payment-page@{version}/dist/truelayer-payment.min.js
or
https://cdn.jsdelivr.net/npm/truelayer-embedded-payment-page@{version}/dist/truelayer-payment.min.js

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

Update your CSP directives:

If you are using CSP (content security policy) then you should whitelist TrueLayer's domain as a valid source for iframes. Example:

 frame-src 'self' https://payment.truelayer-sandbox.com;
 frame-src 'self' https://payment.truelayer.com;

Initialize the embedded-payment-page

Prerequisites:

1. Create a payment using TrueLayer's API
2. Add your return URI to the TrueLayer developer console

Once you have a payment ID or the mandate ID, resource token and a return uri you can initialise the SDK:

import { Payment, Mandate } from 'truelayer-embedded-payment-page'
const payment = Payment({
  payment_id: 'example-string',  Returned on payment creation
  resource_token: 'example-string',  Returned on payment creation
  return_uri: 'example-string',  Where the user is redirected when they exit the payment flow.
})

const mandate = Mandate({
  mandate_id: 'example-string',  Returned on mandate creation
  resource_token: 'example-string',  Returned on payment creation
  return_uri: 'example-string',  Where the user is redirected when they exit the payment flow.
})

You can then start the payment or mandate flow:

payment.start()
mandate.start()

Switch between environments

By default, the SDK will load the sandbox HPP. You can switch to using the production version by setting the production field to true:

import { Payment } from 'truelayer-embedded-payment-page'
const payment = Payment({
  ...,
  production: true
})

Load the HPP in your own DOM node

By default, the SDK will load the HPP inside a modal overlaying your website. If instead you'd like to load it inside your own DOM node, you can do so by setting the target field. Your target node should be at least 320px by 320px. In case of target passed it will be forwarded inside the onDone and the onAbort callbacks

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

const payment = Payment({
  ...,
  target: document.getElementById('my-dom-element-id'),
  onDone: target => {
    console.log('onDone called')
  },
  onAbort: target => {
    console.log('onAbort called')
  }
})

Please be aware that in case of target node you also need to handle the unmount in the related callbacks: onAbort and onDone. The Epp provides also the option to manually unsubscribe to all events listeners present calling directly the unmount method.

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

const payment = Payment({
  ...,
  target: document.getElementById('my-dom-element-id'),
})

// later in the code when needed
payment.unmount()

Callbacks

You can provide a number of callbacks to the embedded-payment-page:

• onLoad the iframe is loaded
• onHandoffStart customer has used QR code to continue with bank app on mobile
• onDone the HPP flow is done
• onAbort the payment has been dismissed by the user
• onError an error occurred and the EPP cannot manage it, the function receives the error thrown

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

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

Additional Configuration

You can customize certain aspects of the Hosted Payments Page from the EPP. The type of color accepted is just hex.

There are two kinds of options: base and extra. The extra options are only available with additional permissions, and if you would like to use these additional customisation options you need to speak to yours TrueLayer contact. In case you try to use some invalid customisation the HPP displays an error indicating the problem.

Base

1. the base color used as a base for everything

default_color: Color

2. the color of the spinner wheel

spinner: { color: Color }

Example

3. the color of the illustrations present in the app

illustration: { color: Color }

Example

Extra

1 the font used on the HPP

font: "Roboto"

Example

2. the style of the buttons for each state (default, hover, active, focus, disabled)

the default state is the state of the button when all others states are excluded

button: {
  default: {
    color: Color,
    background: Color,
    border: {
      color: Color,
      radius: CssPropertyValue,
      width: CssPropertyValue,
      style: CssPropertyValue,
    },
    icon: {
      color: Color,
    }
  },
  ...
}

Example

the icon property refers to an icon present inside the label of the button

Example

3. the style of each element in a list for each state (default, hover, active, focus, selected)

listOption: {
  default: {
    color: Color,
    background: Color,
    border: {
      color: Color,
      radius: CssPropertyValue,
      width: CssPropertyValue,
      style: CssPropertyValue,
    },
    icon: {
      color: Color,
    }
  },
  ...
}

Example

4. the style of the input for each state (default, focus, hover, disabled)

input: {
  default: {
    placeholder: {
      color: Color,
    },
    label: {
      color: Color,
    },
    icon: {
      color: Color,
    },
    border: {
      color: Color,
      radius: CssPropertyValue,
      width: CssPropertyValue,
      style: CssPropertyValue,
    },
    color: Color,
    background: Color,
  },
  ...
}

The configuration lives inside the appearance preperty which is a plain object. Typescript will help with the auto complete.

Example configuration:

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

const payment = Payment({
  payment_id: 'example-string',
  resource_token: 'example-string',
  return_uri: 'example-string',
  appearance: {
    default_color: '#F0FFFF',
    illustration: { color: '#FF00FF' },
    button: {
      default: { background: '#FF00FF' },
      disabled: { color: '#FF00FF' },
      hover: { background: '#FF0000' },
      focus: {
        border: { color: '#FF00FF', radius: '8px', width: '4px' },
      },
    },
    listOption: { selected: { background: '#7700ff' } },
    input: {
      disabled: {
        placeholder: { color: '#0026ff' },
        label: { color: '#0026ff' },
      },
    },
  },
})

Using custom fonts

The truelayer-embedded-payment-page permits the use of font overrides through google fonts only. As an example we will use the Roboto font from google fonts.

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

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

Set a language

By default the SDK will use the browser locale to select an appropriate language for the UI. If needed, you can override this behaviour by specifying the language property using the ISO Alpha-2 code format:

const payment = window.Truelayer.Payment({
  ...,
  language: 'fr'
})

Debug

To enable easy debugging, clients can pass an additional parameter: debug_mode = true. The Widget will log in the console every operation done

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

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

Overriding configuration

The configuration options can also be overridden after the embedded-payment-page is initialized:

import { Payment } from 'truelayer-embedded-payment-page'
const payment = Payment({
  payment_id: 'example-string',
  resource_token: 'example-string',
  return_uri: 'example-string',
  debug_mode: false,
})

payment.start({ debug_mode: true })  from now on debug mode is enabled

Signup+

Note:

Signup+ must now be specified at payment creation, the signup: true property in the configuration options is still supported but will be deprecated in the future.

Example:

{
  "currency": "GBP",
  "payment_method": {...},
	"related_products": {
		"signup_plus": {}
	}
}

The configuration options allow also for the Signup+ text to be displayed (default is false)

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

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

Navigation

The configuration options allow also for the navigation bar to be hidden (default is false).

Please note that in this case the user would not be able to abandon the payment from within the EPP.

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

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

Configure payments/mandate results screen waiting period

To enable this functionality, the client can pass an additional parameter: max_wait_for_result = 60. This option will extend the payment/mandate result waiting period by upto 60 seconds on a per-payment/mandate basis.

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

This option is given to clients to ensure the payment completes within a certain time window, otherwise the payment/mandate can be cancelled.

Please note that in production - if client adds a value of more than 60 seconds, we will override the value and change it back to our max which is 60 seconds.

Please note that in sandbox - if client adds a value more than 60 seconds, we show an error screen / throw an error to the developer so they are aware during their integration phase