Trustly uses legacy Automated Clearing House (ACH) Routing and Account Numbers to initiate a disbursement using real-time Representational State Transfer (REST) Application Programming Interfaces (APIs).

The disbursement process is completed in three steps:

• A bank authorization is created with the Establish API - You collect the customer's Account and Routing Number in your workflow and then pass the information to Trustly with the Establish a Transaction endpoint.
• A disbursement transaction is created with the Deposit API - You initiate a disbursement and pass the transactionId to the Deposit Transaction endpoint.
• Handle event notifications - When the disbursement is completed, Trustly sends an Event Notification with the final disposition of the disbursement.

To manage disbursements, the following operational interfaces are required:

• Event Notifications: This provides real-time status updates for your transactions.
• Reporting: This provides daily Funding and Transaction Reports that you can use for settlement and transaction reconciliation.

Create bank authorizations with the Establish API

Use the Trustly Establish API to create an Authorization Transaction that you can use with the Deposit API.

To initiate the request, pass in the following inputs:

• merchantId: A unique Trustly merchant identifier.
• merchantReference: A unique Merchant Reference identifier that represents your ID for the Authorization request.
• account.accountNumber: This is the account number entered by the sender.
• account.routingNumber: This is the routing number entered by the sender.
• amount: The amount of the transaction. This represents the maximum amount of the transactions that can be processed with the Authorization. If the amount is 0.00, there is no upper bound on the transaction.
• currency: A 3-letter International Organization for Standardization (ISO) Currency Code. Currently only USD and CAD are supported.
• paymentType: The Payment Type of the transaction to create. This should be Disbursement.
• returnUrl: Not used.
• canceUrl: Not used.

Ensure you pass a query string of createTransaction=true on the API Endpoint URL.

You can optionally pass in an account.type (Account Type - Checking or Savings). For a full list of the fields, see the Establish a Transaction reference.

The response is a Trustly Transaction object. An abbreviated example is shown below. Store the transactionId so you can pass it to the Deposit call.

Example request

POST /establish?createTransaction=true

{
  "merchantId": "1002463580",
  "merchantReference": "2eabae90-f466-47e3-99d5-73d0492e8f37",
  "account": {
    "accountNumber": "123456576",
    "routingNumber": "124003116",
    "type": 1
  },
  "amount": "0.00",
  "currency": "USD|CAD",
  "deviceType": "web",
  "paymentType": "Disbursement",
  "returnUrl": "#return",
  "cancelUrl": "#cancel"
}

Example response (abbreviated)

{
    "transaction": {
        "transactionId": "1002613662",
        "transactionType": 1,
        "payment": {
            "paymentId": "1002613661",
            "paymentType": 4,
            "merchantId": "1002463580",
            "account": {
                "type": 1,
                "accountNumber": "123456576",
                "routingNumber": "124003116",
                "source": 0
            },
            "returnUrl": "#return",
            "cancelUrl": "#cancel",
            "amount": "0.00",
        },
        "currency": "USD|CAD",
        "amount": "0.00",
        "status": 0,
        "statusMessage": "Authorized",
        "merchantReference": "2eabae90-f466-47e3-99d5-73d0492e8f37"
    }
}

Create disbursement transactions with the Deposit API

With a valid transactionId from an Authorization request, you can use the Trustly Deposit Transaction to initiate a Disbursement or Payout transaction to a users bank account.

To initiate the request, pass in the following inputs:

• transactionId: Authorization Transaction ID retrieved from a Trustly Deferred or Disbursement Authorization.
• amount: The amount to be sent. Required if the Authorization Transaction amount was 0.00. If not passed, the full amount of the Authorization Transaction will be used.
• merchantReference: A specific merchant reference for this deposit. For example, this could be an merchant order number or the same merchant reference value used in the original establish call.

If successful, the response of this call will be an authorized Disbursement transaction. Updates to the status of the transaction will be sent via Event Notification.

Example request

POST /transactions/1002613662/deposit

amount=25.00&merchantReference=f9c28cd0-bca1-47cb-a776-238b621e66cb

Example response (abbreviated)

{
    "transaction": {
        "transactionId": "1002613685",
        "transactionType": 6,
        "originalTransactionId": "1002613662",
        "payment": {
            "paymentId": "1002580220",
            "paymentType": 2,
        },
        "currency": "USD|CAD",
       "amount": "25.00",
        "status": 2,
        "statusMessage": "Authorized",
        "createdAt": 1556922524381,
        "processedAt": 1556922524393,
        "completedAt": 1556922524621,
        "updatedAt": 1556922524622,
        "ppTrxId": "ptx-CquvTsAaPDvaSB6ywZ2krXGS-sbx",
        "merchantReference": "f9c28cd0-bca1-47cb-a776-238b621e66cb",
        "statusCode": "AC100",
        "recordVersion": 1
    }
}

Handle disbursement transaction event notifications

The following diagram shows the transaction state of a disbursement transaction. Transaction status updates are sent with an Event Notification. You can also retrieve status updates with the Trustly Transactions Report.

1. The Deposit API returns a status of Authorized.
2. Once the transaction is submitted to the network for processing, the transaction is moved to the Processed state.
3. After 3 banking days, if the transaction has not been moved to the Denied state, it is moved to the Completed state.
4. If there are any issues depositing the funds after the transaction has been moved to Completed, it is moved to the Reversed state.

For more information on Event Notifications, refer to Event Notifications .

Testing

The following table lists inputs and expected results that can be used for testing.

Error handling

The following table lists expected errors and suggested actions that are associated with this product. For more information on Error Handling, consult the Errors.