Truelayer Web SDK

A lightweight web SDK for integrating Truelayer's payment services into your web application.

Documentation

Visit docs.truelayer.com for complete installation instructions and API documentation.

Installation

npm install truelayer-web-sdk

Usage

To use the Truelayer Web SDK in your web application, you need to import the initWebSdk function and call it:

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)
  }
  uiSettings: {
    recommendedPaymentMethod: true,
    size: 'large',
    borderRadius: 8,
  },
  production: false,
})

Configuration

The initWebSdk function accepts the following configuration options:

• onDone (function, optional): A callback function that is called when the payment process is completed. It receives an object with a resultStatus property indicating whether the payment was success, failed, or pending.
• onCancel (function, optional): A callback function that is called when the payment process is canceled.
• onError (function, optional): A callback function that is called when an error occurs during the payment process. It receives an optional Error object with details about the error.
• onExpired (function, optional): A callback function that is called when the resource token expires. The callback will not be invoked if the payment status has transitioned to a successful state.
• onPayButtonClicked (function, optional): A callback function that is called when the pay button is clicked.
• onNavigation (function, optional): A callback function that is called when the user visits a new page. It receives a string representing the page name which can have one of the following values: 'cancel' | 'providers' | 'consent' | 'waiting-bank' | 'qr-code' | 'qr-code-loader' | 'return-from-bank' | 'account-selection' | 'checkout' | 'learn-more'
• uiSettings (object, optional): An object containing UI settings.
  • recommendedPaymentMethod (boolean, optional): Determines whether to show the recommended payment method label.
  • size ('small' | 'large', optional):
    • Specifying small makes the web SDK only render the payment button without any surrounding text and without the "learn more" link.
    • Specifying large renders the payment button with the surrounding explanatory text and with the "learn more" link.
    • Defaults to large.
  • borderRadius (number, optional): Indicates the border radius pixel value of the payment button.
  • merchantLogoUri (string, optional): custom logo to display in the merchant position
  • lng (string, optional): 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 lng property using the ISO Alpha-2 code format.
• production (boolean, optional): Indicates whether to use the production environment or not. If false, the sandbox environment is used. Defaults to false.
• maxWaitForResult (number, optional): Defines the maximum waiting time (in seconds) for a final payment result status before displaying the payment result screen.
• hideButton (boolean, optional): Defines a new integration type. Once passed the checkout button is no more present and the Payment Session can be started directly. Integrators call the start function without the mount. The uiSettings does not accept recommendedPaymentMethod, size and borderRadius anymore.
• hostedResultScreen (object, optional): Defines how the SDK behaves when the user completes the Payment. The result would be shown on a new tab of the browser instead of on top of the merchant domain. This behaviour would be particularly useful when the session is started within a Webview on the merchant's app. Settings:
  • returnUri (string, required): where to redirect the user after it sees the result.

The mount function accepts a container as argument (HTMLElement), the dom element where the SDK UI will be rendered.

The start function accepts a payment and initiate the Pay Button which otherwise will remain in the loading state. In case of hideButton equals to true this function will start the Payment Session. Required arguments:

• paymentId (string): The payment identifier.
• resourceToken (string): The resource token.

Examples

const { mount, start } = 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,
})

Alternatively, in case you already have everthing you need when initialising the web-sdk, you can chain the mount and the start functions to obtain the same result all at once.

initWebSdk({ ... })
  .mount(node)
  .start({
    paymentId: payment.id,
    resourceToken: payment.resource_token,
  })

hideButton Case

initWebSdk({ hideButton: true }).start({
  paymentId: payment.id,
  resourceToken: payment.resource_token,
})

Change Log

0.6.6

Bugfix: Enable scrolling on the learn more and result screens when the screen is too small (e. g. in the landscape mode).

0.6.7

New Feature Added onExpired callback, you can listen and to re-init the SDK.

0.7.0

New Feature Added hideButton property, to have a buttonless integration.

0.8.0

New Feature Added hostedResultScreen property.