Web SDK (UK only)
Enable users to authorise payments using the web SDK.
The web SDK is a quick way to integrate a TrueLayer authorisation flow into a webpage, which will enable you to embed a payments UI within your site. The web SDK provides:
- a modern and sleek user experience optimised for conversion, with our latest UI design
- a TrueLayer payment button, optional, embedded right into your site
If you have a third-party in-app web view (eg. WebKit), the hosted payment page or mobile SDKs may be more suitable.
UK Payments only
The web SDK supports single payments in the UK only. This means that it does not yet support any European payment flows and it is only available in English. It is also not compatible with VRP or Signup+.
If you need one of the use cases that we don't support, we recommend that you use the embedded payment page instead.
Before you start
Make sure that you are ready for payment retries. That means:
- ensuring that you recognise the
attempt_failed
payment status - passing the
retry
parameter in the payment creation request
If you have a content security policy, add TrueLayer’s domains to your allowlist to ensure that you can accept payments. These domains are:
- Sandbox:
https://app.truelayer-sandbox.com
- Live:
https://app.truelayer.com
Below is an example of a CSP HTTP header:
frame-src 'self' https://app.truelayer.com https://app.truelayer-sandbox.com
Web SDK demo
Click the button below to see the Web SDK experience for first-time and returning user flows. Select Monzo at provider selection to ensure that the authorisation flow succeeds.
Dynamic Payment button
When your user makes a payment through the web SDK, you have the option of showing them a dynamic button at checkout, which contains the most relevant banks to them based on the banks they've used previously, or the most used banks in their market.
When the user clicks the button, they continue the flow in a modal on top of your page.
There are two size options to choose from when integrating the web SDK:
- The small option includes a Pay button only.
- The large option includes a Pay button and supporting information.
We recommend using this option, to help users understand the payment method. However, you also have the option to start the web SDK at a later stage, and use your own button at checkout.
For more about changing the button size, or using the web SDK without the button, see Customise the Web SDK .
Payment retries for web SDK
To initiate a payment with the web SDK, you need to enable payment retries. Retries enable several features that make the payment experience much smoother for your users.
To enable this feature, you need to include an empty retry
parameter in your payment creation request.
The retry object is located inside the payment_method
object. It looks like this:
{
//...
"payment_method": {
"type": "bank_transfer",
//...
"provider_selection": {
//...
},
//...
"retry": {}
},
//...
}
Alternatively, contact us to get payment retries set up for your account.
When a retry fails, the payment moves into the attempt_failed
status. Like the authorizing
status, this payment status does not trigger a webhook, but you can make a GET request to monitor this payment.
Your user can retry a payment as many times as they like before the payment expires in 15 minutes.
How to integrate the web SDK
The web SDK is a JavaScript library, which means you can integrate in two ways. You can use a package manager, like NPM, or inject it to a HTML webpage using script tags.
Integrate the web SDK with a package manager
Use these commands to set up the Web SDK with the NPM, Yarn, or PNPM package managers:
- NPM:
npm i truelayer-web-sdk
- YARN:
yarn add truelayer-web-sdk
- PNPM:
pnpm install truelayer-web-sdk
Integrate the web SDK with Script tags
If you want to integrate the web SDK using script tags, it is hosted on the jsdelivr and unpkg CDNs.
You can access the latest version of the web SDK at these URLs:
- jsdeliver:
https://cdn.jsdelivr.net/npm/truelayer-web-sdk/dist/sdk.min.js
- unpkg:
https://unpkg.com/truelayer-web-sdk/dist/sdk.min.js
If you need a specific version, use these links and specify the version in place of the text {version}
:
- jsdelivr:
https://cdn.jsdelivr.net/npm/truelayer-web-sdk@{version}/dist/sdk.min.js
- unpkg:
https://unpkg.com/truelayer-web-sdk@{version}/dist/sdk.min.js
Create a payment and initialise the SDK
You need to pass a payment ID and resource token to initialise the web SDK. To do this, you need to create a payment.
We recommend that you do this when you load the checkout page. This leaves the shortest time possible between payment creation and initialising the SDK, which avoids issues related to payment expiry.
At the highest level, to accept a payment with the web SDK, you need to:
- create a payment
- initialise the SDK
- mount the container where the Pay button will be
- initiate a payment, obtain its
id
andresource_token
and pass these to thestart
function with yourreidrect_uri
- have your user authorise the payment
- run the
cleanup
function after the payment is done
These are each handled by different functions. mount
displays the button in a loading state. The start
function activates the button and displays the correct bank logos.
Below are two examples:
initWebSdk({
//...
})
.mount(node)
.start({
paymentId: payment.id,
resourceToken: payment.resource_token,
})
const { mount, start, cleanup } = initWebSdk({
// ...
})
// later, when the target for the button is ready
mount(node)
// later, when the payment is available
start({
paymentId: payment.id,
resourceToken: payment.resource_token,
})
For optimal user experience, we recommend that you mount the container and initiate the payment as early as possible when the user arrives at your checkout page.
The user flow for payment authorisation
Below is an example of the steps that you and your user take to authorise a payment:
- The user selects the payment button.
- The web SDK uses this
id
andresourceToken
to begin the authorisation process. The authorisation screens displays as an overlay within your web page. - Your user selects their bank on the provider selection screen.
If a bank is unavailable, it's greyed out on the provider selection screen, so the user can attempt to use a different bank. - Your user enters any additional information that the bank requires, and confirms.
- If their bank supports app-to-app authentication, desktop users see a QR code. Scanning the code enables them to continue the payment using the banking app on their phone. They can also continue on desktop.
- The SDK redirects your user to their bank's website or app.
- Once the authorisation is complete, the bank redirects the user back to the web SDK, to see the result of the payment.
- The user closes the modal and the webpage consumes the callback.
You can also save your users' payment details for a smoother journey when they pay you the next time. To learn more about this, read our docs on the Save details feature.
Handle payment expiry
This is an optional step, but we highly recommend it.
Because you create a payment before you initialise the widget, a payment might expire before the user can complete the flow. For example, if the user pauses during the authorisation flow to do something else, the payment may expire by the time they return to the flow. Payments expire after 15 minutes if the user doesn't start the authorisation flow.
The retry feature allows users to retry failed payments within that 15-minute window, but beyond that a new payment will need to be created for the user to continue.
We recommend that you track this timeout period, and if necessary re-initialise the web SDK with a new payment once it expires. You can track the expiry either with your own timer, or by using the exp
property of the resource token. This property has a timestamp that marks when it expires.
Re-initialise the Web SDK
To re-initialise the WebSDK, call the initWebSdk
function again with a new payment id
.
If the Web SDK encounters an error and needs to restart, you also need to re-initialise the SDK.
Below is an example:
cleanup()
initWebSdk({ ... })
mount(node)
start({
newPaymentId: payment.id,
resourceToken: payment.resource_token,
})
Callbacks
You can include a set of callbacks within the initWebSdk
function to inform you when certain events in the authorisation flow have been completed (or when the user chooses to cancel the payment).
These are:
-
onPaymentButtonClicked
: The user selected the TrueLayer Pay by bank app payment method. -
onDone
: The Web SDK flow is complete. This can return three different results:String received Payment status or webhook it corresponds to 'success'
The payment_creditable
webhook , which is thesettled
status by default.'pending'
The authorized
orexecuted
statuses .'failed'
The failed
status . -
onCancel
: The user cancelled the authorisation flow.
This does not mean the payment itself is cancelled. The user can restart it by selecting the TrueLayer Pay by bank app again. -
onError
: Something went wrong (for example, there’s a bug in the SDK) and we can’t process the payment. -
onExpired
: A callback function the SDK returns when the paymentresource_token
expires. You won't receive this if the payment status transitioned to a successful state. -
onNavigation
: A callback function the SDK returns when the user visits a new page. It returns a string that represents the page name, which can have one of the following values:String received Position in authorisation flow it corresponds to 'checkout'
Your checkout page. 'learn-more'
The "Learn more" modal. 'cancel'
The user cancelling the payment. 'providers'
The provider selection screen. 'account-selection'
The bank account selection screen. 'consent'
The consent screen. 'waiting-bank'
Waiting for their banking provider to authenticate. 'qr-code'
The QR code handoff screen. 'qr-code-loader'
The loader screen on desktop after the user has handed off to pay on mobile. 'return-from-bank'
Redirect back to your app after the user has authorised or cancelled the payment, or if authorisation fails.
Location of the onNavigation
callbacks in the flow
onNavigation
callbacks in the flowThese are examples of the screens that each of the onNavigation
callbacks respond to within the TrueLayer payment authorisation flow:
Wait to complete a payment
You may want to allow more time for the payment to transition to a terminal status (settled
or failed
) before we redirect the user back to you. This is useful if you need to know the outcome of a payment for certain before the redirect.
To do this, include a maxWaitForResult
field within the initWebSdk
function and add a number to represent the maximum waiting time in seconds. This value controls how long the user waits before they are shown a result screen, if the payment has not reached a terminal status.
If you specify a higher maxWaitForResult
, it's likely you'll receive a result of pending
for the onDone
callback.
If you don't include this field, the default waiting period is 4 seconds. The maximum waiting period that you can set is 60 seconds.
This is an example of the maxWaitForResult
field within an integration, with a waiting period of 40 seconds.
} = initWebSdk({
maxWaitForResult: 40,
uiSettings: {
size: 'small',
recommendedPaymentMethod: true,
Switch between sandbox and production modes
By default, the Web SDK is set to sandbox mode.
To switch to production, include a production
field within the initWebSdk
object and set it to true
.
Below is an example of the production
mode turned on:
} = initWebSdk({
maxWaitForResult: 40,
production: true,
Full request example
This is an example of the web SDK within an integration, with UI settings and callbacks configured.
import { initWebSdk } from '@truelayer/web-sdk'
const {
// Function to mount the container where the Pay button will be
mount,
// Function to initiate the Pay button with a payment
start,
// Function to remove event listeners used by the SDK, when the SDK is not longer needed.
cleanup,
// Function to dynamically open the learn more modal
openLearnMoreModal,
} = initWebSdk({
onDone: info => {
console.log(`Payment status: ${info.resultStatus}`)
},
onCancel: () => {
console.log('Payment cancelled')
},
onError: error => {
console.error('Payment error:', error)
},
onPayButtonClicked: () => {
console.log('Pay button clicked')
},
onNavigation: page => {
console.log('Page:', page)
},
onExpired: () => {
alert('The payment has expired')
},
uiSettings: {
recommendedPaymentMethod: true,
size: 'large',
borderRadius: 8,
},
production: false,
})
Updated 4 days ago