SDKs

Web (JavaScript)

Integrate the Trustly Lightbox and Select Bank Widget into your web application.
View as Markdown

To integrate the Trustly Lightbox into your web application, you must set up the JavaScript SDK. This process involves loading the library, configuring the UI options, and initializing the request.

Prerequisites

  • Your backend must be configured to generate the establishData payload and requestSignature. See frontend integration for details on the client-server boundary and payload requirements.
  • You must have your accessId to initialize the script. You can find this in the Trustly Merchant Portal (Settings > Developer Settings).
  • Your development domain must be added to the allow list in your Trustly account settings.

Load the JavaScript library

  1. Include the Trustly JavaScript library on every page where you intend to launch the Trustly Lightbox. Add the following <script> tag to your application page’s <head> or immediately before the closing </body> tag:

    Sandbox:

    1<script src="https://sandbox.trustly.one/start/scripts/trustly.js?accessId=YOUR_ACCESS_ID"></script>

    Production:

    1<script src="https://trustly.one/start/scripts/trustly.js?accessId=YOUR_ACCESS_ID"></script>

  2. Replace YOUR_ACCESS_ID with the accessId Trustly provides during onboarding.

    You must always load the script directly from trustly.one. Do not download, bundle, or host the script from a custom domain.

Configure UI options

  1. Pass a TrustlyOptions object as the second argument to establish or selectBankWidget to customize the behavior and appearance of the Trustly Lightbox:

    1let TrustlyOptions = {
    2  hideCloseButton: true,
    3  dragAndDrop: true,
    4  widgetContainerId: "trustly-widget-id",
    5  widgetTiles: 12, // Number of bank tiles to display (12, 9, or 6)
    6  fontFamily: "Arial, sans-serif",
    7  fontSize: "14px"
    8};

  2. Configure UI and callback parameters as needed for your integration:

ParameterDescription
hideBackIf true, hides the back button (`<`) within the Trustly Lightbox. Default is false.
hideCloseButtonIf true, hides the close button (`x`). Default is false.
hideSelectBankBackIf true, hides the back button only on the Select Bank screen. Default is false.
dragAndDropIf true, allows the user to drag the Trustly Lightbox modal. Default is true.
widgetContainerIdRequired for selectBankWidget. Specifies the ID of the HTML element to contain the widget. Default is null.
widgetTilesConfigures the number of bank tiles displayed in the embedded widget. Accepted desktop values are 12 (3x4 grid), 9 (3x3 grid), or 6 (2x3 grid). Mobile automatically renders a 2-column grid.
fontFamilyCustomizes the font family of the widget text to match your site’s branding.
fontSizeCustomizes the font size of the widget’s benefit message and labels.
benefitMessageConfigures the dynamic benefit message displayed within the widget (for example, tailored for gaming or standard e-commerce).
onReturnCallback function executed when the user completes the flow and returns to your application (ideal for Single Page Applications to avoid full redirects).
onCancelCallback function executed when the user closes or aborts the Trustly Lightbox before completing the transaction.

Initialize the request

Call the SDK function to launch the UI. You can choose between the Select Bank Widget (inline) or the Establish (modal) function.

FunctionDescription
establishLaunch with button: Launches the full-page Lightbox directly. Best for standard checkout flows.
selectBankWidgetEmbedded Widget: Renders an inline component displaying popular banks. Selecting a bank opens the Trustly Lightbox.

Select Bank Widget (embedded)

The Select Bank Widget is an optional, inline component that displays the most popular banks and provides a search field. Selecting a bank from the widget opens the Trustly Lightbox.

Select Bank Widget

  1. Add a container element (such as a <div>) to your HTML layout where you want the widget to render.

  2. In your TrustlyOptions object, specify a widgetContainerId matching the ID of your HTML container element.

  3. Call Trustly.selectBankWidget with your establishData and TrustlyOptions:

    1let TrustlyOptions = {
    2  widgetContainerId: "trustly-widget-id" // The ID of the <div> where the widget will render
    3};
    4
    5Trustly.selectBankWidget(establishData, TrustlyOptions);

Launch the Lightbox (standard)

  1. Add a checkout button (such as Pay with Trustly) to your application layout.

  2. Configure your button’s click event listener to invoke Trustly.establish(establishData, TrustlyOptions):

    Trustly Lightbox

    1// Call this when the user clicks your payment button
    2Trustly.establish(establishData, TrustlyOptions);

Embed branded buttons

If your integration uses the Express Checkout or Sign-In workflows, you must use Trustly’s hosted branded buttons to remain compliant with branding requirements. Do not create your own button images for these specific flows.

Trustly provides a script that securely embeds these buttons directly into your page via an iframe, ensuring the assets are always up to date.

Express Checkout button

  1. Add a container element to your page where you want the Express Checkout button to render:

    1<!-- Container for the Express Checkout button -->
    2<div id="trustly-express-checkout-btn"></div>

  2. Initialize Trustly.renderButton and attach your Trustly.establish call to onClick:

    1<script>
    2  // Ensure establishData and TrustlyOptions are defined in your scope prior to calling onClick
    3  Trustly.renderButton('trustly-express-checkout-btn', {
    4    type: 'express_checkout',
    5    theme: 'light', // Options: 'light', 'dark'
    6    onClick: function() {
    7      Trustly.establish(establishData, TrustlyOptions);
    8    }
    9  });
    10</script>

Sign-In button

  1. Add a container element to your page where you want the Sign-In button to render:

    1<!-- Container for the Sign-In button -->
    2<div id="trustly-sign-in-btn"></div>

  2. Initialize Trustly.renderButton and attach your Trustly.establish call to onClick:

    1<script>
    2  // Ensure establishData and TrustlyOptions are defined in your scope prior to calling onClick
    3  Trustly.renderButton('trustly-sign-in-btn', {
    4    type: 'sign_in',
    5    theme: 'light', // Options: 'light', 'dark'
    6    onClick: function() {
    7      Trustly.establish(establishData, TrustlyOptions);
    8    }
    9  });
    10</script>

Complete HTML example

You cannot run the following example without a valid requestSignature. The SDK will fail to load if this field is missing or incorrect. Before proceeding, use your backend to generate a signature for your test payload. See Generate request signatures to get the code to generate the signature in Node.js or Java.

1<html>
2  <head>
3    <meta name="viewport" content="width=device-width, initial-scale=1" />
4    <script>
5      const TrustlyOptions = {
6        hideCloseButton: false,
7        dragAndDrop: true,
8        widgetContainerId: 'widget'
9      };
10    </script>
11    <script src="https://sandbox.trustly.one/start/scripts/trustly.js?accessId=YOUR_ACCESS_ID"></script>
12  </head>
13  <body style="margin: 0;">
14    <div id="widget"></div>
15    <script>
16      const establishData = {
17        accessId: 'YOUR_ACCESS_ID',
18        merchantId: 'YOUR_MERCHANT_ID',
19        merchantReference: 'UNIQUE_REF_123', // Must be unique per transaction
20        description: 'transaction description',
21        currency: 'USD',
22        amount: '0.00',
23        paymentType: 'Deferred', // Use 'Instant' for one-time payments
24        requestSignature: 'SIGNATURE_FROM_BACKEND', // generate this server-side
25        customer: {
26          name: 'John Smith',
27          address: {
28            country: 'US'
29          }
30        },
31        returnUrl: 'https://merchant.com/return',
32        cancelUrl: 'https://merchant.com/cancel'
33      };
34
35      Trustly.selectBankWidget(establishData, TrustlyOptions);
36    </script>
37  </body>
38</html>