Send payouts using online banking

Trustly Payouts allow you to transfer funds directly to a customer’s bank account using the secure Trustly Lightbox. This is ideal for gaming withdrawals, wallet withdrawals, or gig-economy payments.

Unlike manual payouts which require you to handle sensitive banking data, this workflow authenticates the customer with their online banking credentials. This enables instant verification, reduces fraud, and supports Real-Time Payments (RTP).

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.
• Legal agreement: Ensure your contract supports Payouts and Deposits.

Payout workflow

The following diagram illustrates the Payout workflow for a new user (first-time bank connection). This process involves the customer authorizing their account for the first time before the merchant initiates a deposit.

The following table provides details for each step of the payout workflow.

Authenticate the customer

To send money, you first need to establish a connection with the customer’s bank. This generates a transactionId that represents the authorized account.

Use the Establish method with paymentType: 'Deferred'. This creates an open authorization without authorizing a charge or debit from the customer’s account.

Example SDK call

1
var establishData = {
2
  accessId: 'YOUR_ACCESS_ID',
3
  merchantId: 'YOUR_MERCHANT_ID',
4
  merchantReference: 'payout_session_12345',
5
  description: 'Connect Bank for Withdrawals',
6
  currency: 'USD',
7
  amount: '0.00', 
8
  paymentType: 'Deferred', 
9
  requestSignature: 'GENERATED_SIGNATURE_FROM_BACKEND', // Required for security
10
  customer: {
11
    externalId: 'user_123',
12
    name: 'John Doe',
13
    email: 'john.doe@example.com',
14
    address: {
15
        country: 'US'
16
    }
17
  },
18
  returnUrl: 'https://merchant.com/payout/success',
19
  cancelUrl: 'https://merchant.com/payout/cancel'
20
};
21
22
/* Open the Lightbox */
23
Trustly.establish(establishData, TrustlyOptions);

Once the customer completes the flow, Trustly redirects them to your returnUrl. You must capture the transactionId from the URL parameters.

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

Check eligibility (optional)

Before sending funds, you may want to check if the customer’s bank supports Instant Payouts (Real-Time Payments).

Call the Get Transactions API using the transactionId you obtained when you authenticated the customer. For example:

Endpoint: GET /transactions/{transactionId}

Review the payment.paymentProvider.instantPayoutAvailable boolean field for the following values:

• true: The bank supports instant settlement (RTP/FedNow).
• false: The payout will process via standard ACH (1-3 business days).

Send funds (deposit)

Use the Deposit a Transaction API to transfer funds to the authorized account. For example:

Endpoint: POST /transactions/{transactionId}/deposit

Request parameters

Example request

$
curl -X POST https://sandbox.trustly.one/api/v1/transactions/{transactionId}/deposit \
>
  -u "YOUR_ACCESS_ID:YOUR_ACCESS_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "amount": "25.00",
>
    "merchantReference": "payout_001",
>
    "instantPayoutRequest": true
>
  }'

Handle the response

The following table describes the response statuses returned by the Deposit a Transaction API and the recommended actions for each status.

Event notifications

Payouts are asynchronous. Even instant payouts undergo processing states. You must listen for Event notifications to confirm the final status. The API returns the following statuses:

• PROCESSED: Trustly submitted the funds to the payment network.
• COMPLETED: The funds settled in the customer’s account.
• DENIED: The payout failed before submission.
• REVERSED: The payout was successfully submitted but later failed or returned by the bank. You should return the funds to the customer’s wallet balance.