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

# 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](/integrate/accept-payments/instant-payments) (One-time transactions)
* [Trustly Pay](/integrate/accept-payments/trustly-pay) (Recurring or deferred authorizations)
* [Payouts](/integrate/send-money/send-payouts-using-online-banking) (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](/sdks/javascript) 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](/sdks/i-os), [Android](/sdks/android), [React Native](/sdks/react-native), or [Cross-platform frameworks](/sdks/mobile-web).

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

```mermaid
sequenceDiagram
  participant User
  participant Client as Merchant Frontend
  participant Server as Merchant Backend
  participant Trustly as Trustly UI / API

  User->>Client: A
  Client->>Server: B
  Server-->>Client: C
  Client->>Trustly: D
  Trustly-->>User: E
  User->>Trustly: F
  Trustly-->>Client: G
  Trustly-->>Server: H
```

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](/integrate/core-concepts/the-establish-data-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](/integrate/api-fundamentals/secure-requests-and-signature-validation/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:

* [Accept Instant Payments](/integrate/accept-payments/instant-payments)
* [Authorize and capture](/integrate/accept-payments/trustly-pay)

## Next steps

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

* [**Web SDK (JavaScript) →**](/sdks/javascript)
* [**iOS SDK →**](/sdks/i-os)
* [**Android SDK →**](/sdks/android)
* [**React Native SDK →**](/sdks/react-native)
* [**Other mobile frameworks →**](/sdks/mobile-web)