About Trustly Pay

Trustly Pay enables end-users to send 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
Capture	The transaction type that finalizes a payment and triggers the actual movement of funds from the user to the merchant. A capture can be performed as a single operation, or after a successful pre-authorization.
Deposit	The transaction type used to send funds from the merchant to the consumer's bank account. In the context of a digital wallet, this is typically used to process a user pay-out.
Establish Data	The JSON object containing all configuration parameters (such as amount, currency, and customer details) required to initialize a customer authorization.
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 front end redirects to and from Trustly, event notifications, and webhooks. It ensures that the request originated from a verified source and has not been tampered with.
Select Bank Widget	An embeddable UI component that allows the customer to search for and select their bank directly on your checkout page, bypassing the initial screen of the Trustly Lightbox.
Split Token	An authentication mechanism where the credential is split between the merchant and Trustly. You retain the merchant-side token to identify the user, which must be paired with the Trustly-side token to authorize a transaction. This shared architecture ensures that sensitive data is never held in a single location, while still allowing returning users to bypass the bank login step.
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).
Unsettled	A transaction has been submitted to the banking network but funds have not yet cleared. During this period, the funds are not yet available for pay-out or use.
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 constructs the Establish Data object to trigger the selectBankWidget or 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 status as it processes through the banking network. Transaction status updates are sent with Event Notifications and can be retrieved with the Trustly Transactions Report.

Capture and deposit status

The following diagram shows the transaction status flow for a Capture (pay-in) or Deposit (pay-out) transaction.

Refund and reclaim status

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

Status definitions

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

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 status.
Completed/Denied: If the transaction has not been moved to the Denied status, it moves to the Completed status.
Reversed: If there are issues settling the funds after the transaction has moved to Completed (such as a return), it transitions to the Reversed status.