Send payouts

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

Unlike Disbursements, which require manual account entry, Payouts utilize the Trustly Lightbox to authenticate the customer and retrieve a secure token (transactionId). You can then use this token to deposit funds immediately or at a later date.

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, where the customer authorizes their account and the merchant subsequently initiates a deposit.

sequenceDiagram
  participant Customer
  participant Merchant
  participant Trustly
  participant Bank

  Note over Customer, Merchant: Stage A: Authentication
  Customer->>Merchant: A
  Merchant->>Trustly: B
  Trustly-->>Customer: C
  Customer->>Trustly: D
  Trustly->>Merchant: E

  Note over Merchant, Trustly: Stage B: Deposit Initiation
  Merchant->>Trustly: F
  Trustly->>Bank: G
  
  rect rgb(240, 248, 255)
      Note right of Trustly: Asynchronous
      Trustly-->>Merchant: H
  end

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

Workflow Step	Participant	Action	Description
A	Customer	Requests Payout	The customer selects Withdraw or Cash out on your website.
B	Merchant	Calls Establish API	The frontend initializes the SDK with `paymentType: 'Deferred'` to create an authorization.
C	Trustly	Opens UI	The Trustly Lightbox launches.
D	Customer	Authenticates	The customer logs in to their bank to authorize the account connection.
E	Trustly	Redirects	Trustly redirects the customer to your `returnUrl` with a `transactionId`.
F	Merchant	Deposits	Your system calls the Deposit API using the `transactionId` and the payout amount.
G	Trustly	Sends Credit Instruction	Trustly sends the instruction and funds to the customer's bank.
H	Trustly	Sends Webhook	Async: Trustly sends a webhook to your backend confirming the final settlement status.

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

var establishData = {
  accessId: 'YOUR_ACCESS_ID',
  merchantId: 'YOUR_MERCHANT_ID',
  merchantReference: 'customer_session_8829',
  description: 'Connect Bank for Withdrawals',
  currency: 'USD',
  amount: '0.00', // Authorization only
  paymentType: 'Deferred', // Required for Payouts
  returnUrl: 'https://merchant.com/profile/success',
  cancelUrl: 'https://merchant.com/profile/cancel'
};

/* Open the Lightbox */
Trustly.establish(establishData, TrustlyOptions);

Security Note: You must generate a requestSignature for the payload to prevent tampering. See Securing requests.

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 Transaction 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 API to transfer funds to the authorized account. For example:

Endpoint: POST /transactions/{transactionId}/deposit

Request parameters

Parameter	Description
`amount`	The amount to credit to the customer's account.
`merchantReference`	Your unique identifier for this payout order.
`instantPayoutRequest`	Optional. Set to `true` to request Real-Time Payment (RTP) settlement.

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 outlines the response statuses returned by the Deposit API and the recommended actions for each status.

Status	Description	Action
AUTHORIZED	The payout request is accepted.	The payout request is accepted. Record the transaction and wait for the `COMPLETED` webhook
DECLINED	The request failed.	Do not deduct funds. Notify the customer.

Event notifications

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

PROCESSED: The funds have been submitted to the payment network.
COMPLETED: The funds have 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.