Send disbursements

To send funds to a customer by letting them log in to their bank without the need to handle sensitive account numbers, see Payouts.

The Disbursements API allows you to send funds to a customer using their Account Number and Routing Number. This is a manual entry workflow where you collect the banking details in your own UI and pass them to Trustly with an API.

When you handle raw banking data (Account and Routing numbers), you are responsible for maintaining Payment Card Industry Data Security Standard (PCI DSS) and National Automated Clearing House Association (NACHA) compliance and ensuring the security of this sensitive data.

Prerequisites

Sandbox credentials: You need your accessId and accessKey.
Legal agreement: Your contract must explicitly allow the use of the Disbursement payment type.

Integration workflow

The following diagram illustrates the API-only workflow for Disbursements. Unlike Payouts, there is no Lightbox interaction.

sequenceDiagram
  autonumber
  participant Merchant
  participant Trustly
  participant Bank

  Note over Merchant: Stage A: Authorization
  Merchant->>Trustly: 1. POST /establish (paymentType='Disbursement')
  Trustly-->>Merchant: 2. Returns transactionId

  Note over Merchant, Bank: Stage B: Deposit
  Merchant->>Trustly: 3. POST /deposit (amount, transactionId)
  Trustly->>Bank: 4. Initiate Credit
  
  rect rgb(240, 248, 255)
      Note right of Trustly: Asynchronous
      Trustly-->>Merchant: 5. Webhook (Completed)
  end

The following table details each step of the Disbursement workflow.

Step	Participant	Action	Description
1	Merchant	Calls Establish	You send the customer's account and routing number to Trustly to create a token.
2	Trustly	Returns ID	Trustly validates the format and returns a `transactionId`.
3	Merchant	Calls Deposit	You initiate the transfer using the `transactionId` and the specific amount.
4	Bank	Credits	The banking network processes the credit to the customer's account.
5	Trustly	Notifies	Async: Trustly sends a webhook to your backend confirming the funds have settled.

Create a bank authorization

Use the Establish API to tokenize the customer's banking information. This creates a transaction record you can reference for the deposit.

Important: You must append createTransaction=true to the endpoint URL for this request to work correctly.

Endpoint: POST /establish

Required parameters

Parameter	Description
`paymentType`	Must be set to `Disbursement`.
`account.routingNumber`	The 9-digit American Bankers Association (ABA) routing number collected from the customer.
`account.accountNumber`	The customer's bank account number.
`merchantReference`	Your unique identifier for this customer or session.
`amount`	The maximum limit for future transactions processed with this authorization. Set to `0.00` to indicate no upper bound.
`currency`	The 3-letter ISO currency code. Currently, only `USD` and `CAD` are supported.

Example request

POST /establish?createTransaction=true

{
  "merchantId": "YOUR_MERCHANT_ID",
  "merchantReference": "user_123_ref",
  "paymentType": "Disbursement",
  "currency": "USD",
  "amount": "0.00", 
  "account": {
    "routingNumber": "124003116",
    "accountNumber": "123456576",
    "type": 1
  },
  "returnUrl": "https://not-used.com",
  "cancelUrl": "https://not-used.com"
}

returnUrl and cancelUrl are required fields in the schema but are not used in this flow because there is no user redirect. You can pass placeholder URLs.

The API returns a Transaction object. You must store the transactionId from this response, as it is required to initiate the subsequent Deposit call.

Example response

Store the transactionId returned in the response.

{
  "transaction": {
    "transactionId": "1002613662",
    "status": 0,
    "statusMessage": "Authorized",
    "payment": {
      "paymentType": 4,
      "account": {
        "accountNumber": "123456576",
        "routingNumber": "124003116"
      }
    }
  }
}

Send funds (deposit)

Once you have the transactionId, use the Deposit API to initiate the transfer of funds.

Endpoint: POST /transactions/{transactionId}/deposit

Example request

curl -X POST https://sandbox.trustly.one/api/v1/transactions/1002613662/deposit \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "25.00",
    "merchantReference": "payout_001"
  }'

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.	Deduct the funds from the customer's balance in your system and wait for the `Completed` webhook.
DECLINED	The request failed.	Do not deduct funds. Notify the customer.

Event notifications

Disbursements are asynchronous. You must implement a webhook listener to determine when the money actually arrives. See Handle webhooks.

The following are the statuses that can be returned:

Processed: The file has been sent to the Federal Reserve (ACH).
Completed: The funds have settled in the customer's account (typically T+1 or T+2).
Reversed: The transaction failed after processing. For example, the account is closed.

Testing

You can use the following test data to simulate a successful Disbursement authorization in the Sandbox environment.

Field	Value	Result
Routing Number	`124003116`	Valid ABA Routing Number
Account Number	`123456575`	Simulates a valid account

For a complete list of test scenarios, including error triggers and other account types, see Testing.