About Trustly Pay

Trustly Pay enables end-users to pay or receive funds by signing in to their online banking interface directly within your website or application. This secure, direct-to-bank model reduces fraud risks and transaction costs while offering a familiar authentication experience for users.

Terminology

The following table lists the core concepts and components used in a Trustly Pay integration.

Term	Definition
Establish Data	The JSON object containing all configuration parameters (such as amount, currency, and customer details) required to initialize a transaction.
Lightbox	The secure, Trustly-hosted user interface where the customer selects their bank and logs in to authorize a payment.
Merchant Reference	A unique string generated by your system to identify a specific order or transaction. This value persists through the entire transaction lifecycle and appears in reports.
Request Signature	A cryptographic hash used to secure API requests. It ensures that the request originated from a verified source and has not been tampered with.
Split Token	A secure token generated during a successful authorization. You store this token to identify returning users, allowing them to skip the bank login step for future payments.
Transaction ID	A unique, 15-character numeric identifier generated by Trustly for every transaction. You use this ID to interact with the Trustly API (for example, to capture funds or issue refunds).
Webhook / Event Notification	An asynchronous message sent by Trustly to your server (`notificationUrl`) to inform you of status changes (such as when a pending payment becomes authorized).

How it works

The interaction begins when the user selects online banking as their payment method. Your application triggers the selectBankWidget or constructs the Establish Data object to launch the Trustly Lightbox. The user authenticates with their financial institution and selects the desired account. Once authorized, the user is redirected to your returnUrl with a generated transactionId, allowing you to capture funds or retrieve account data immediately.

The following diagram illustrates the end-to-end workflow of a Trustly Pay transaction, showing the sequence of interactions between your application, the user, and the Trustly API.

Transaction lifecycle

Once a transaction is initiated with the API, it moves through specific states as it processes through the banking network. Transaction status updates are sent via Event Notifications and can be retrieved with the Trustly Transactions Report.

Capture and deposit states

The following diagram shows the transaction state flow for a Capture (Payin) or Deposit (Payout) transaction.

Refund and reclaim states

The following diagram shows the transaction state flow for a Refund or Reclaim transaction.

State definitions

Whether you are processing a Capture, Deposit, Refund, or Reclaim, the transaction lifecycle includes the following stages:

Authorized: The API creates the transaction with this initial status.
Processed: Once Trustly submits the transaction to the banking network, it moves to the Processed state.
Completed/Denied: After approximately 3 banking days, if the transaction has not been moved to the Denied state, it moves to the Completed state.
Reversed: If there are issues settling the funds after the transaction has moved to Completed (such as a return), it transitions to the Reversed state.