Trustly can be used with legacy ACH Routing and Account Numbers to initiate a Disbursement using our real-time REST APIs. This is a three step process:

1. Create a Bank Authorization with the Establish API. Collect the customers Account and Routing Number in your flow. Pass this information to Trustly via the Establish a Transaction.
2. Create a Disbursement Transaction with the Deposit API. When the time comes to initiate a Disbursement, pass the transactionId created in Step 1 to the Trustly Deposit Transaction.
3. Handle Event Notifications. Once the Disbursement is completed, Trustly will send an Event Notification with the final disposition of the Disbursement.

In addition, you should implement the following operational interfaces:

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

Creating Bank Authorizations with the Establish API

Use the Trustly Establish API to create an Authorization Transaction that can be used with 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 will be no upper bound on the transaction.
• currency: 3-letter 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, consult the Establish a Transaction.

The response will be a Trustly Transaction object. An abbreviate example is shown below. You'll want to store the transactionId so it can be passed 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"
    }
}

Creating 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
    }
}

Handling Event Notifications

Disbursement Transactions

The following diagram shows the Transaction State of a Disbursement transaction. Transaction status updates are sent via Event Notification and can also be retrieved via 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.

Further Reading

• Establish a Transaction
• Deposit Transaction
• Event Notifications