Key concepts

Understanding the core components and security models that power Trustly Pay by Bank solutions can be helpful before you integrate with Trustly.

The Trustly model (A2A)

Trustly operates on an Account-to-Account (A2A) model. Unlike credit card networks that rely on intermediaries (schemes, acquirers, issuers), Trustly uses Open Banking APIs to connect merchants directly to the consumer's bank account.

• No chargebacks: Because the consumer authenticates directly with their bank, payments are verified and significantly harder to dispute than card transactions.
• Push payments: In most workflows, the consumer pushes funds to merchants, rather than merchants pulling funds from a card number.

The Trustly Lightbox

The Trustly Lightbox is the secure, hosted user interface where all consumer interactions occur. It is the only component your user sees during the transaction.

• Bank selection: Users select their financial institution from a dynamic list.
• Authentication: Users log in using their familiar online banking credentials (username and password, biometrics, or multi-factor authentication).
• Authorization: The user explicitly consents to the payment or data sharing.

To render the Trustly Lightbox, see Integrate the client-side SDK.

The Select Bank Widget

The Select Bank Widget is a JavaScript component that embeds the bank selection list directly into your application's UI, rather than waiting for the Trustly Lightbox to open.

• Embedded integration: The widget renders within a container <div> on your page, allowing it to sit alongside other form fields.
• Pre-selection: Selecting a bank in the widget passes the paymentProviderId to the Establish call, launching the Trustly Lightbox directly into the login screen for that institution.
• Bank ordering: The Trustly API dynamically sorts the list of banks based on the user's device type and geographic location.

Security and tokenization

Trustly employs a multi-layered security model that combines tokenized credentials with cryptographic signatures to protect sensitive banking data and verify request authenticity.

Split Token architecture

Trustly uses a unique split token model to ensure security. When a user connects their account:

• Merchant token: Merchants receive a token representing the user's identity.
• Trustly token: Trustly retains a token representing the bank connection.

A transaction can only be authorized when both tokens are present. If a merchant's database is compromised, the tokens held by the merchant cannot be used to move money without the matching Trustly half.

Request signatures

To prevent man-in-the-middle attacks, all redirects (to and from the Trustly Lightbox) and asynchronous notifications (Webhooks) are secured with a request signature. Merchants must verify this signature using their secret API key to ensure the request genuinely originated from Trustly.

Transaction types

Understanding the difference between transaction types is critical for choosing the right integration workflow.

• Deposit (Pay-in): Moving funds from the consumer to the merchant.
  • Instant: Funds are verified and guaranteed immediately. See Accept Instant Payments.
  • Deferred: Funds are authorized now but captured later. See Accept payments with Trustly Pay.
• Payout: Moving funds from the merchant to the consumer.
  • Standard: Processed via ACH (1-3 business days).
  • Instant: Processed via RTP or FedNow networks for immediate settlement. See Send payouts using online banking.
• Retrieval (Data): Fetching read-only data without moving money.
  • Used for identity verification (KYC), balance checks, or account ownership verification.
  • Supports Micro-deposits (MCD) as a fallback verification method when online banking login is not available. See Verify accounts using online banking.

Event notifications (Webhooks)

Because bank payments can be asynchronous (taking seconds to days to settle), Trustly relies on webhooks to keep merchant systems synchronized.

Instead of polling the API, merchants provide a notificationUrl. Trustly sends a JSON payload to this URL whenever a transaction state changes. For example, from Pending to Completed or Denied. Listening to these events is the only reliable way to track the final status of a payment.

For configuration details and example payloads, see Handle webhooks.