Trustly's Cashflow APIs provide a straightforward method of accessing users' aggregated financial information, including their account balances, deposits, withdrawals, and other related information.

In this tutorial, we will guide you through the process of collecting a user's Bank Authorization and using the Retrieve Account Summary API which allows you to retrieve aggregated financial information of a user’s account(s) (Balance, Deposits, Withdrawals, Overdrafts, NSFs (non-sufficient funds), and NSF fees for periods of 7, 30, and 90 days).

Overview

The basic steps of this tutorial are to:

1. Integrate the Trustly UI to Create an Authorized Transaction.
2. Retrieve the user's aggregated financial information using the Account Summary API
3. Use the retrieved information for further processing or decision making.

Create an Authorized Transaction

📘

Using the Trustly UI SDKs

As with most Trustly use cases, retrieving account data begins with acquiring a "Bank Authorization" from a user. This requires integrating a Trustly UI library in the user-facing client of your application. For a more detailed guide on these steps see the 📑 Trustly UI Guide and if you are integrating with a mobile application see the 📱Mobile Apps Guide.

1. In your website or mobile application, include the appropriate Trustly UI SDK in order to render the Select Bank Widget or launch the Lightbox
2. Define the Establish Data to be passed to Trustly and set the paymentType property to the string "Retrieval" in order to create the correct transaction type.

{
  "merchantId": "YOUR_MERCHANT_ID",
  "accessId":"YOUR_ACCESS_ID",
  "merchantReference": "merchantReference",
  "paymentType": "Retrieval",
  "customer": {
  	"name": "Joe User",
    "email": "[email protected]"
    }
  }
}

3. The user will select their bank from the Trustly UI, authenticate and select an account to create a successful authorization.
4. After a successful authorization, the Trustly UI will redirect the user to the returnUrl provided in the Establish Data. If the user closes the Trustly UI or the authorization fails for any other reason, the user will be redirected to the provided cancelUrl. See handling the redirect URLs for more information on collecting the transactionId and other important details at these endpoints.

After successfully acquiring a Bank Authorization, the transactionId associated with the authorization can be used to cal any of the Transactions-related APIs. These can be used for creating payments, deposits, retrieving basic account data, and retrieving basic user data. The primary steps for retrieving CashFlow data are to to retrieve a summary of the user's bank account activity and optionally retrieve categorized raw transaction data for further processing.

Account Activity Data

The Account Summary API allows you to retrieve aggregated financial information of a user’s account(s) (Balance, Deposits, Withdrawals, Overdrafts, NSFs (non-sufficient funds), and NSF fees for periods of 7, 30, and 90 days). This data can be used to inspect spending hygiene, account balance history, NSF risk, and other parameters to simplify the credit application process and make better-informed credit decisions.

GET Account Summary

Execute a GET request to the Account Summary endpoint, replacing the {transactionId} path parameter with the transactionId of the Bank Account Authorization created in the Create an Authorized Transaction step.

GET https://sandbox.trustly.one/api/v1/transactions/:id/accountSummary

The Get Account Summary API returns a JSON response with three top level properties:

• customerId (string): Trustly identifier for the customer record.
• lastUpdated (integer): Epoch timestamp for when the account summary was last aggregated.
• summary (array): List of accounts, and relevant summary data, associated with the customer.

This response was abbreviated, for more details see the Account Summary API definition.

{
    "customerId": "780001",
    "lastUpdated": 1633471332000,
    "summary": [
        {
            "selectedAccount": true,
            "currency": "USD",
            "nameOnAccount": "John Doe",
            "accountNumber": "67675545",
            "routingNumber": "557787",
            "aggregations": [
                {
                    "days": 7,
                    "activityEarliestDate": 1631750403554,
                    "activityLatestDate": 1632268808707,
                    "balanceMax": "10320.32",
                    "balanceMin": "9700.10",
                    "balanceAvg": "9860.13",
                    "depositCount": 2,
                    "depositAmountTotal": "620.22",
                    "depositAmountMax": "500.00",
                    "withdrawalCount": 1,
                    "withdrawalAmountTotal": "299.90",
                    "withdrawalAmountMax": "299.90",
                    "overdraftCount": 0,
                    "overdraftAmountTotal": "0.00",
                    "nsfCount": 0,
                    "nsfFeeAmountTotal": "0.00"
                },
                {
                    "days": 30,
                     ...
                },
                {
                    "days": 90,
                     ...
                }
            ]
        }
    ]
}

Categorized Transactions

The Categorized Transactions API allows you to return raw transaction data for a given account. given transaction. You call the Categorized Transaction API by executing a GET request to the Categorized Transaction endpoint, where transactionId is the Bank Account Authorization transaction id. Please refer to the Get Categorized Transaction API definition in the API Reference for more information.

GET Account Activity

Make a GET request to the Account Activity endpoint, replacing the {transactionId} path parameter with the transactionId of the Bank Account Authorization created in the Create an Authorized Transaction step.

The Get Account Activity API endpoint returns a JSON response with a single parent property: transactions. The transactions property contains an array of raw bank transaction objects. Each transaction object contains a number of properties, a few are listed below, for the entire schema, see the GET Account Activity API reference.

• category: Object containing type and description properties associated with the category of the transaction.
• amount: The amount of the transaction
• currency: The currency associated with the transaction

In addition to these properties, properties indicating the date, location and type of the transaction are also included. See an example response is shown below:

{
  "activities": [
    {
      "category": {
        "type": 1001,
        "description": "Payment - Utilities"
      },
      "amount": 23.43,
      "description": "Description of the transaction",
      "isBillPay": true,
      "isDirectDeposit": true,
      "isExpense": true,
      "isFee": true,
      "isIncome": true,
      "isInternational": true,
      "isOverdraftFee": false,
      "isPayrollAdvance": true,
      "isSubscription": false,
      "notes": "Bank Notes",
      "bankDescription": "Bank description of the charge",
      "postedAt": "2024-01-17",
      "transactedAt": "2024-01-16",
      "updatedAt": "2024-01-17",
      "transactionLatitude": -22.90278,
      "transactionLongitude": -43.2075,
      "cashFlowType": "CREDIT",
      "currency": "USD"
    },
    {
      "category": {
        "type": 2002,
        "description": "Investment - Cryptocurrency"
      },
      "amount": 34.43,
      "description": "Description of the transaction",
      "isBillPay": false,
      "isDirectDeposit": true,
      "isExpense": true,
      "isFee": false,
      "isIncome": true,
      "isInternational": true,
      "isOverdraftFee": false,
      "isPayrollAdvance": true,
      "isSubscription": false,
      "notes": "Bank Notes",
      "bankDescription": "Bank description of the charge",
      "postedAt": null,
      "transactedAt": "2024-01-16",
      "updatedAt": "2024-01-17",
      "transactionLatitude": -22.90278,
      "transactionLongitude": -43.2075,
      "cashFlowType": "DEBIT",
      "currency": "USD"
    }
  ]
}

Conclusion

In this tutorial, we have covered the steps necessary to retrieve a user's account activity data associated with their authorized financial account. We covered integrating the Trustly UI to create an authorized transaction and then used that authorized transaction to retrieve account summary data and raw transactional data. With this information, you can begin to build powerful financial applications that leverage Trustly's advanced technology to save your users time and offer better insights.

After completing this tutorial, visit the Testing Guide and the common Errors reference in order to handle edge cases your users may come across. Additionally, you may want to consider adding additional user data to your Trustly integration or supporting Trustly in your mobile applications.