Integrate the client-side SDK

The Trustly client-side SDK handles the secure, frontend user interaction for your web application. It initializes the Trustly Lightbox, allowing users to select their bank and authorize transactions without sharing credentials with your server.

This is the prerequisite step for all Trustly web payment workflows. You must implement this frontend logic to generate the transactionId required by your backend for:

Instant Payments (One-time transactions)
Trustly Pay (Recurring or deferred authorizations)
Payouts (Sending funds to users)

Topic scope

This guide focuses strictly on rendering the user interface. It does not cover:

Capturing or sending funds
Handling webhooks
Managing the transaction lifecycle

For those workflows, complete this guide first, then proceed to Accept Instant Payments or Authorize and capture.

Prerequisites

Trustly credentials: You need your accessId to initialize the script. You can find this in the Trustly Merchant Portal (Settings > Developer Settings).
Whitelisting: Ensure your development domain is whitelisted in your Trustly account settings.

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

Web integration (JavaScript)

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

Load the JavaScript library

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:

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

Production:

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

Replace YOUR_ACCESS_ID with the accessId provided by Trustly during onboarding.

Construct the Establish Data object

To initiate a transaction, you must create a JavaScript object containing the transaction parameters. Trustly refers to this as the Establish Data object.

Do not pass Personally Identifiable Information (PII) such as names or email addresses in the description field. All customer PII must be passed within the customer object.

Example payload

{
  "merchantId": "YOUR_MERCHANT_ID",
  "accessId":"YOUR_ACCESS_ID",
  "requestSignature": {requestSignature},
  "merchantReference": {unique_merchant_payment_identifier},
  "description": "any additional user-friendly descriptive information for the payment",
  "paymentType": "Deferred",
  "currency": "USD",
  "amount": "0.00",
  "customer": {
    "name": "Joe User",
    "email": "[email protected]",
    "address": {
      "address1": "2000 Broadway St",
      "city": "Redwood City",
      "state": "CA",
      "zip": "94063",
      "country": "US"
    }
  },
  returnUrl: "https://yourapp.com/path/return",
  cancelUrl: "https://yourapp.com/path/cancel"
}

Field requirements

The following fields require specific formatting or logic to ensure security and compliance:

Field	Requirement and Logic
`paymentType`	Required. The workflow type. Use `Instant` for one-time payments. Use `Deferred` for Trustly Pay (long-running authorizations).
`requestSignature`	Required. You must calculate a cryptographic signature to secure the request payload. See Securing requests.
`amount`	• Set to `0.00` for an open-ended authorization (no upper limit). • Enter a specific value (e.g., `100.00`) to define a maximum limit for the authorization.
`displayAmount`	If `amount` is set to `0.00` or includes fees not yet captured, use this field to display the correct estimated total to the user within the Lightbox.
`verifyCustomer`	Electronic Gaming Clients Only: Must be set to `true` to trigger necessary identity verification checks.
`customer`	All Personally Identifiable Information (PII) such as name and email must be passed in this object. Do not pass PII in the `description` field.
`merchantReference`	Required. Must be unique for each transaction to avoid duplicates.

Electronic Gaming Clients: You are required to set verifyCustomer to true and populate the complete customer object for identity verification compliance.

Request signature

The requestSignature field is required for all Trustly SDK requests. It is a cryptographic signature generated on your backend to verify the integrity of the transaction parameters. Without a valid requestSignature, the SDK will fail to launch the Lightbox.

Always generate the signature on a secure server. Never expose your API secret key in client-side code.

Example: requestSignature: 'SIGNATURE_FROM_BACKEND' // e.g., hash(payload + secretKey)

To generate the signature, see Secure requests and validate signatures.

Handling SDK errors

The Trustly SDK may throw errors if the requestSignature is missing, invalid, or mismatched with the transaction payload. Other common SDK errors include missing required fields or failure to load the Trustly script.

For error codes and lifecycle statuses, see the relevant payment workflow topics:

Configure UI options

You can customize the behavior and appearance of the Trustly Lightbox by passing a TrustlyOptions object as the second argument to establish or selectBankWidget. For example:

let TrustlyOptions = {
  hideCloseButton: true,
  dragAndDrop: true
};

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`.

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.

To render the widget, your TrustlyOptions object must include a widgetContainerId matching the ID of an HTML element on your page.

let TrustlyOptions = {
  widgetContainerId: "trustly-widget-id" // The ID of the <div> where the widget will render
};

Trustly.selectBankWidget(establishData, TrustlyOptions);

Launch the Lightbox (standard)

This method typically uses a Pay with Trustly button. When the user clicks the button, your application calls the establish function to open the modal.

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

Complete HTML example

<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <script>
      var TrustlyOptions = {
        closeButton: false,
        dragAndDrop: true,
        widgetContainerId: 'widget'
      };
    </script>
    <script src="https://sandbox.trustly.one/start/scripts/trustly.js?accessId=YOUR_ACCESS_ID"></script>
  </head>
  <body style="margin: 0;">
    <div id="widget"></div>
    <script>
      var establishData = {
        accessId: 'YOUR_ACCESS_ID',
        merchantId: 'YOUR_MERCHANT_ID',
        merchantReference: 'UNIQUE_REF_123', // Must be unique per transaction
        description: 'transaction description',
        currency: 'USD',
        amount: '0.00',
        paymentType: 'Deferred',
        requestSignature: 'SIGNATURE_FROM_BACKEND', // generate this server-side
        customer: {
          name: 'John Smith',
          address: {
            country: 'US'
          }
        },
        returnUrl: 'https://merchant.com/return',
        cancelUrl: 'https://merchant.com/cancel'
      };

      Trustly.selectBankWidget(establishData, TrustlyOptions);
    </script>
  </body>
</html>

Mobile SDKs

Trustly provides native SDKs for iOS and Android. These SDKs encapsulate the same Establish workflow described earlier, but handle UI rendering and callbacks natively.

If you are building a native mobile application, refer to the specific documentation for your platform:

When using native mobile SDKs, the returnUrl and cancelUrl properties in your Establish Data are not required. Instead, the SDKs provide onReturn and onCancel callback functions to handle the responses.