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

In this tutorial, we will guide you through collecting a user's bank authorization and using Account Data features, which allow you to retrieve aggregated financial information for users’ accounts.

Overview

The basic steps of this tutorial are to:

1. Integrate the Trustly UI to Create an Authorized Transaction;
2. Call Get account activity summary API to retrieve the user's aggregated financial information;
3. Further steps.

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 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"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 themself, 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, 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 call any Transaction-related APIs, which can be used to create payments and deposits. After receiving the Data Ready event, you can also use it to retrieve the data from the user and their accounts.

Retrieve Account Summary Data

⚠️

Data Ready Event Notification

Warning, calling any of the Account Data APIs for a new authorization transaction prior to receiving the DataReady event can result in partial data being returned.

To ensure optimal performance, wait to receive the DataReady event prior to making a request to an calling an Account Data API.

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.

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/{transactionId}/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.

{
    "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,
                     ...
                }
            ]
        }
    ]
}

Check Account Summary API Reference for more details.

Besides the Account Summary, you can also retrieve the raw account activity data through the Get Account Activity API, which is a nice next feature to explore. You can also find other data-related features here: Account Data

Next steps

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 the account summary data. With this information, you can start building powerful financial applications that leverage Trustly's advanced technology to save your users time and offer better insights.

Visit the Testing Guide and the common Errors reference 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.