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

$3

``
npm i truelayer-embedded-payment-page


or

yarn add truelayer-embedded-payment-page

or

pnpm add truelayer-embedded-payment-page
`

$3

`html
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:

`html
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:

`typescript
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:

`typescript
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:

`typescript
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

`typescript
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.

`typescript
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

`typescript
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:

`typescript
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.

`typescript
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:

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

$3

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

`typescript
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:

`typescript
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+

$3

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:

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

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

`typescript
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.

`typescript
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()
`

$3

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.

`typescript
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