Authorize and capture with Trustly Pay

Trustly Pay is a deferred payment workflow designed for high-frequency merchants, such as iGaming operators, digital wallets, and trading platforms.

Unlike standard one-time payments, Trustly Pay establishes a long-running bank authorization. This allows you to generate a secure token once and use it for multiple future transactions. For example, pulling funds or pushing winnings without requiring the user to log in again.

Compare Trustly Pay and Instant Payments

Core capabilities

The Trustly Pay workflow supports the following primary operations:

• Pay-ins (Capture): Pull funds from the user's bank account to your platform.
• Payouts (Deposit): Push winnings or withdrawals back to the user's bank account. In Trustly API terminology, a Deposit transaction sends money to the user.

In addition, Trustly offers the following APIs to manage the transaction lifecycle:

• Refund transaction: Use to refund a previously completed Capture transaction.
• Reclaim transaction: Use to refund a previously completed Payout (Deposit) transaction.
• Cancel transaction: Use to cancel a previously authorized Authorization or unsettled Capture transaction.

Payment workflow

The following diagram illustrates the two-phase lifecycle of a Trustly Pay transaction, starting with the initial user authorization and followed by the server-side funds capture.

sequenceDiagram
  participant User
  participant Client as Merchant Frontend
  participant Server as Merchant Backend
  participant Trustly

  Note over User, Trustly: Phase 1: Bank Authorization
  User->>Client: A
  Client->>Trustly: B
  Trustly-->>User: C
  User->>Trustly: D
  Trustly-->>Client: E
  Client->>Server: F

  Note over User, Trustly: Phase 2: Capture Funds
  Server->>Trustly: G
  Trustly-->>Server: H
  Trustly-)Server: I

The following table describes each step in the workflow, corresponding to the lettered annotations in the diagram.

Prerequisites

• Client-side SDK: You must integrate the JavaScript SDK (Web) or Mobile SDK to launch the Trustly UI. See Integrate the Client-Side SDK.
• Sandbox credentials: You need your accessId and accessKey. Contact Trustly Support if you do not have them.
• Legal agreement: Ensure your non-disclosure agreement (NDA) and commercial agreements are signed.

Create a bank authorization

The foundation of Trustly Pay is the Establish call. This launches the Lightbox and generates a transactionId that represents the authorized user.

Configure the transaction

Create an establishData object to define the transaction parameters. To create a deferred authorization, you must set the paymentType to Deferred. For example:

var establishData = {
  accessId: 'YOUR_ACCESS_ID',
  merchantId: 'YOUR_MERCHANT_ID',
  merchantReference: 'user_session_8829',
  description: 'Wallet funding',
  currency: 'USD',
  amount: '0.00',
  paymentType: 'Deferred', // Critical for Trustly Pay
  requestSignature: 'GENERATED_SIGNATURE', // Critical for security
  customer: {
    name: 'Jane Doe',
    address: {
        country: 'US'
    }
  },
  returnUrl: '[https://merchant.com/return](https://merchant.com/return)',
  cancelUrl: '[https://merchant.com/cancel](https://merchant.com/cancel)'
};

Launch the Lightbox

Call Trustly.establish() passing both your transaction data and your options object (if configured). For example:

Trustly.establish(establishData, TrustlyOptions);

To configure TrustlyOptions, see Integrate the Client-Side SDK.

Handle the redirect

Once the user successfully authorizes the request, Trustly redirects them to your returnUrl. If the user cancels, Trustly redirects them to your cancelUrl.

Example Return URL: https://merchant.com/return?transactionId=1002633191&status=2

You must capture and store the transactionId from the URL parameters. This ID is the unique key you'll use to execute all subsequent API requests. You should also confirm that the status parameter is 2 (Authorized). For a complete list of transaction statuses, see Status codes.

Enable Trustly Remember Me (optional)

Trustly Remember Me significantly reduces friction for returning users and increases conversion rates by enabling a seamless, one-click payment experience.

When the user completes the authorization, Trustly generates a secure splitToken. You can use this token to recognize the returning user and allow them to pay in the future with a single click, bypassing the bank login process entirely.

To enable this functionality, ensure you provide the user's email, phone, and externalId in the customer object of your establishData.

For implementation details, see Enable Trustly Remember Me.

Capture funds

Once you have a valid bank authorization (transactionId), you can pull funds from the user's account into your merchant account using the Capture API.

Endpoint: POST /transactions/{transactionId}/capture

Replace {transactionId} with the ID from the original bank authorization.

Request parameters

Example request

curl -X POST https://sandbox.trustly.one/api/v1/transactions/{transactionId}/capture \
  -u "YOUR_ACCESS_ID:YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10.00",
    "merchantReference": "order_12345"
  }'

Response handling

The Capture API is asynchronous. The immediate response is typically Pending. You must wait for a webhook to confirm the final status.

Send funds (payouts)

To send winnings or withdrawals back to the user's bank account, use the Deposit API. See Send payouts.

Event notifications

Trustly Pay relies on the ACH network, so transaction statuses are asynchronous. You must configure a webhook listener to track when funds actually settle.

Key events for the Trustly Pay workflow include:

• debit: Confirms a successful Pay-in (Capture).
• credit: Confirms a successful Payout (Deposit).

See Handle webhooks.

Refresh bank authorization

Bank authorizations may expire or require refreshing. For example, if a user changes their bank password. See Refresh bank authorization

Error codes

The following table lists the error codes you may encounter during pay-in or payout requests.

For detailed user messaging recommendations for each error code, see Status codes and type definitions.