Frontend integration

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

Launching the UI is the prerequisite step for all Trustly payment workflows. You will use this frontend logic to securely authenticate the user and generate the transactionId required by your backend for:

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

Frontend integration is limited to the universal client-server handshake required to render the user interface. It does not handle capturing funds, processing webhooks, or managing the transaction lifecycle—those actions are securely managed by your backend server.

Available platforms

Trustly provides client-side libraries and SDKs for web and native mobile applications. Choose the platform that matches your architecture:

Web (JavaScript): Follow the instructions on the Web SDK page to integrate the JavaScript Lightbox into your web application.
Mobile SDKs: If you are building a native mobile app, refer to the specific documentation for your platform: iOS, Android, React Native, or Cross-platform frameworks.

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.

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 exactly what happens at each step of the 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).

The `establishData` object

To initiate a transaction, your backend must generate an object containing the transaction parameters and a cryptographic signature. Trustly refers to this as the establishData payload.

For a complete list of required fields and payload examples for your specific platform, see The establishData object.

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.

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:

Next steps

After understanding the client-server boundary and generating your payload, proceed to the platform-specific integration: