Client-side integration guide

The Trustly client-side SDK handles the secure frontend interaction for your web app. It initializes the Trustly Lightbox, letting your users select their bank and authorize transactions without passing sensitive credentials to your server.

This is the prerequisite step for all Trustly web payment workflows. You’ll use 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)

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.

Roles and responsibilities

Before you start the integration, understand the strict boundary between the client-side application and the backend server.

Client-side application (Frontend): Renders the Trustly Lightbox and guides the user through bank selection. The frontend never holds secret keys and never generates security signatures.
Backend server (Backend): Stores API keys securely, generates the required requestSignature, captures funds, and processes webhooks.

Prerequisites

Trustly credentials: You need your accessId to initialize the script. You can find this in the Trustly Merchant Portal (Settings > Developer Settings).
Allow lists: Add your development domain to the allow list in your Trustly account settings.

Transaction workflow

The following diagram illustrates the transaction flow and handoff between your client-side application, your backend server, and the Trustly UI. It shows the secure generation of the request signature prior to launching the Lightbox.

The following table details each step of the client-side integration workflow.

Workflow Step	Action	Description
A	User initiates payment	The user clicks a checkout button, such as Pay with Trustly, on your client-side application.
B	Client requests payload	Your frontend requests the `establishData` object and cryptographic signature from your secure backend server.
C	Server generates payload	Your backend securely generates the `requestSignature` using your secret key and returns the complete, signed payload to the frontend.
D	Client calls SDK	Your frontend calls the Trustly SDK (`Trustly.establish`) using the securely signed payload.
E	Trustly launches UI	The Trustly Lightbox opens, prompting the user to select their financial institution.
F	User authenticates	The user signs into their online banking securely within the Lightbox and authorizes the transaction.
G	Redirect to URL	Trustly closes the Lightbox and redirects the user back to your frontend through the `returnUrl` (or `cancelUrl` if they aborted).
H	Webhook notification	Trustly sends an asynchronous webhook event to your backend server confirming the final transaction status (Authorized).

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

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

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>

Replace YOUR_ACCESS_ID with the accessId Trustly provides 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. Pass all customer PII within the customer object.

Example payload

1 {
2   "merchantId": "YOUR_MERCHANT_ID",
3   "accessId": "YOUR_ACCESS_ID",
4   "requestSignature": "&#123;requestSignature&#125;",
5   "merchantReference": "&#123;unique_merchant_payment_identifier&#125;",
6   "description": "any additional user-friendly descriptive information for the payment",
7   "paymentType": "Deferred",
8   "currency": "USD",
9   "amount": "0.00",
10   "customer": {
11     "name": "Joe User",
12     "email": "joe.user@email.com",
13     "address": {
14       "address1": "2000 Broadway St",
15       "city": "Redwood City",
16       "state": "CA",
17       "zip": "94063",
18       "country": "US"
19     }
20   },
21   "returnUrl": "https://yourapp.com/path/return",
22   "cancelUrl": "https://yourapp.com/path/cancel"
23 }

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. Calculate a cryptographic signature on your backend server 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 (for example, `100.00`) to define a maximum limit for the authorization.
`displayAmount`	If you set `amount` to `0.00` or include fees not yet captured, use this field to display the correct estimated total to the user within the Lightbox.
`verifyCustomer`	Electronic Gaming Clients Only: Set to `true` to trigger necessary identity verification checks.
`customer`	Pass all Personally Identifiable Information (PII) such as name and email in this object. Do not pass PII in the `description` field.
`merchantReference`	Required. Provide a unique reference 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.

Generate the request signature

All Trustly SDK requests require the requestSignature field. Your backend generates this cryptographic signature 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' // For example, hash(payload + secretKey)

To generate the signature, see Generate request signatures.

Handle 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:

1 let TrustlyOptions = {
2   hideCloseButton: true,
3   dragAndDrop: true
4 };

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.

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.

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

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.

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

Test with a complete example

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       var TrustlyOptions = {
6         closeButton: 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       var 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>

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, you do not need the returnUrl and cancelUrl properties in your Establish Data. Instead, the SDKs provide onReturn and onCancel callback functions to handle the responses.

Next steps

After configuring your frontend to launch the UI, you must handle the payment on your server.

Accept Instant Payments → One-time payment transactions with immediate fund verification.
Authorize and Capture → Recurring or deferred authorizations with Trustly Pay.