> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://amer.developers.trustly.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://amer.developers.trustly.com/_mcp/server. # Web (JavaScript) 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](/integrate/core-concepts/integrate-client-sdk) 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 ` ``` **Production**: ```html ``` 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: ```javascript let TrustlyOptions = { hideCloseButton: true, dragAndDrop: true, widgetContainerId: "trustly-widget-id", widgetTiles: 12, // Number of bank tiles to display (12, 9, or 6) fontFamily: "Arial, sans-serif", fontSize: "14px" }; ``` 2. Configure UI and callback parameters as needed for your integration: | Parameter | Description | | :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hideBack` | If `true`, hides the back button (`` `<` ``) within the Trustly Lightbox. Default is `false`. | | `hideCloseButton` | If `true`, hides the close button (`` `x` ``). Default is `false`. | | `hideSelectBankBack` | If `true`, hides the back button **only** on the Select Bank screen. Default is `false`. | | `dragAndDrop` | If `true`, allows the user to drag the Trustly Lightbox modal. Default is `true`. | | `widgetContainerId` | Required for `selectBankWidget`. Specifies the ID of the HTML element to contain the widget. Default is `null`. | | `widgetTiles` | Configures 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. | | `fontFamily` | Customizes the font family of the widget text to match your site's branding. | | `fontSize` | Customizes the font size of the widget's benefit message and labels. | | `benefitMessage` | Configures the dynamic benefit message displayed within the widget (for example, tailored for gaming or standard e-commerce). | | `onReturn` | Callback function executed when the user completes the flow and returns to your application (ideal for Single Page Applications to avoid full redirects). | | `onCancel` | Callback 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. | Function | Description | | :----------------- | :---------------------------------------------------------------------------------------------------------------------- | | `establish` | **Launch with button:** Launches the full-page Lightbox directly. Best for standard checkout flows. | | `selectBankWidget` | **Embedded 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](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/trustly.docs.buildwithfern.com/9db28589843da511b967027d792404c6df7811660efbec4b89d0e538f00b1b94/docs/assets/north-america/9881a49-Payment_Options.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260827%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260827T062124Z&X-Amz-Expires=604800&X-Amz-Signature=dddae02fd2b4bdf28201e0b03be7c14a5e94160f5911f0683a6de3039d8b91e0&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) 1. Add a container element (such as a `
`) 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`: ```javascript let TrustlyOptions = { widgetContainerId: "trustly-widget-id" // The ID of the
where the widget will render }; Trustly.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](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/trustly.docs.buildwithfern.com/ade5be97f85522bf95d535b9ad878311a6d942fed540a8fcdf38a769fd7b3381/docs/assets/north-america/c59cfa3-Widget_lightbox2.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260827%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260827T062124Z&X-Amz-Expires=604800&X-Amz-Signature=51a22400850d0684524c94a9fd6bea6a6de3d3cc71c3af71fa9743cf3615adc7&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject) ```javascript // Call this when the user clicks your payment button Trustly.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: ```html
``` 2. Initialize `Trustly.renderButton` and attach your `Trustly.establish` call to `onClick`: ```html ``` ### Sign-In button 1. Add a container element to your page where you want the Sign-In button to render: ```html
``` 2. Initialize `Trustly.renderButton` and attach your `Trustly.establish` call to `onClick`: ```html ``` ## 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](/integrate/api-fundamentals/secure-requests-and-signature-validation/generate-request-signatures) to get the code to generate the signature in Node.js or Java. ```html
```