truelayer-web-sdk v0.4.0

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.
• 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.
• production (boolean, optional): Indicates whether to use the production environment or not. If false, the sandbox environment is used. Defaults to false.

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