Choose an integration
Integrating Trustly solutions allows your customers 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.
Before you begin, you must select the integration model that best fits your business needs.
Prerequisites
- Client-side SDK: All Trustly pay-in, pay-out, and data workflows rely on the client-side SDK to present the Trustly Lightbox to the user. See Integrate the client-side SDK to get started.
- QR Code API: The Trustly Scan and Pay workflow requires server-side integration with the QR Code API to generate dynamic payment codes for physical devices.
Pay-in workflow
Trustly provides integration models for both online and physical environments. Your choice depends on whether you need to charge a user once, establish a reusable connection, or fund a physical device.
| Feature | Instant payments | Trustly Pay | Trustly Scan and Pay |
|---|---|---|---|
| Workflow type | One-step (Authorize + Pay) | Two-step (Authorize → Capture) | Physical-to-Digital (QR Code → Mobile Auth) |
| Best for | E-commerce, one-time purchases, guest checkout. | iGaming, sports betting, digital wallets, trading platforms. | Physical casinos, Electronic Gaming Machines (EGMs). |
| User experience | User logs in and approves a specific amount in one session. | User authorizes the account once; you capture funds or send payouts later. | User scans a QR code on a physical machine to fund it with their mobile device. |
| API interaction | paymentType: 'instant' (Client-side) | paymentType: 'Deferred' (Client-side) | POST /qrcode/token (Server-side) |
| Implementation | See Accept Instant Payments | See Authorize and Capture | See Integrate Trustly Scan and Pay |
Pay-out workflow
If you need to send funds to a customer (gaming withdrawals, gig-economy payments), you must choose between the modern payouts flow or the legacy Disbursements flow.
| Feature | Payouts (Recommended) | Disbursements |
|---|---|---|
| Data handling | Tokenized. You handle a secure transactionId. | Raw Data. You handle Account and Routing numbers. |
| User experience | Customer logs in through the Trustly Lightbox. | Customer manually types bank details into your UI. |
| Compliance | Low burden (Trustly handles the banking data). | High burden. You are responsible for PCI/NACHA data security. |
| API parameter | paymentType: 'Deferred' | paymentType: 'Disbursement' |
| Implementation | See Send Payouts | See Send Disbursements |
Retrieve data workflow
Use the a data workflow if you need to verify information or retrieve financial insights without processing a monetary transaction. This is common for Know Your Customer (KYC) checks, balance inquiries, and account ownership verification.
| Feature | Identity and Financial Data | Account Ownership (MCD) |
|---|---|---|
| Workflow type | Information and retrieval | Verification |
| Best for | KYC and Anti-Money Laundering (AML) compliance, lending decisions, financial planning apps, and pre-filling user profiles. | Verifying account ownership for Automated Clearing House (ACH) or Electronic Funds Transfer (EFT) setup when instant payments are not available. |
| User experience | User logs in to their bank to grant access. Trustly fetches the requested data (name, address, balance, transaction history). | User logs in. If instant verification fails, Trustly initiates a micro-deposit that the user verifies later. |
| API interaction | paymentType: 'Retrieval' | Handled automatically as a fallback or explicitly configured. |
| Implementation | See Verify accounts and retrieve data | See Verify account ownership |
Terminology
The following table lists the core concepts and components used across all Trustly integrations.
| Term | Definition |
|---|---|
| Capture | The transaction type that finalizes a payment and triggers the actual movement of funds from the consumer 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. |
| EGM | Electronic Gaming Machine. Any physical slot machine or video terminal in a physical casino where a player places a wager using Trustly Scan and Pay. |
| Establish data | The JSON object containing all configuration parameters (such as amount, currency, and customer details) required to initialize a transaction. |
| Instant payout | A payout processed with Real-Time Payment (RTP) or FedNow, resulting in near-instant settlement to the customer's account. |
| 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. |
| RTP/FedNow | Real-Time Payment network (RTP) or FedNow network. These are the underlying bank networks that enable Instant Payout settlement. |
| 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. |
| 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. |
| TPAS | Trustly Payment Agent Service. The integration layer that handles the connection between the casino's system (CMS) and Trustly for Trustly Scan and Pay transactions. |
| 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. |
Transaction lifecycle
Regardless of which integration model you select, money moves through the banking network in a predictable lifecycle. Trustly provides visibility into this lifecycle through API status updates and event notifications.
Payment states (capture and deposit)
When you collect funds (Capture) or send funds (Deposit), the transaction moves through the following states:
- Authorized: The request has been accepted by Trustly.
- Processed: Trustly has submitted the transaction to the banking network.
- Completed: The funds have settled. This typically occurs after three banking days.
- Denied: The transaction failed. For example, due to insufficient funds.
- Reversed: The transaction was completed but later returned. For example, an administrative return.
Refund states
When you issue a Refund back to a user, the transaction follows a similar but distinct path:
Refunds progress through the same Authorized and Processed states as capture and deposit transactions before reaching Completed.
Updated about 21 hours ago