Web SDK (UK only)

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:

1. create a payment
2. initialise the SDK
3. mount the container where the Pay button will be
4. initiate a payment, obtain its id and resource_token and pass these to the start function with your reidrect_uri
5. have your user authorise the payment
6. 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:

1. The user selects the payment button.
2. The web SDK uses this id and resourceToken to begin the authorisation process. The authorisation screens displays as an overlay within your web page.
3. 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.
4. Your user enters any additional information that the bank requires, and confirms.
5. 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.
6. The SDK redirects your user to their bank's website or app.
7. Once the authorisation is complete, the bank redirects the user back to the web SDK, to see the result of the payment.
8. 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 the settled status by default.
  'pending'	The authorized or executed 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 payment resource_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

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