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.
3. When the Trustly Lightbox opens, the user selects their bank from the list, authenticates, and selects their account.
4. After a successful authorization, the Lightbox will redirect the user to the returnUrl provided in the Establish Data.
5. Create a Redirect URL where your application server will collect the details of the new Trustly transaction, including the transactionId and other important properties to associate with the user who created the authorized transaction.

A visual of this workflow can be seen below:

After successfully acquiring a Bank Authorization, the primary steps for retrieving account data are to to retrieve the users bank account and routing information and optionally retrieve additional user information such as name, address, email, etc.

Retrieve Account Summary 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,
                     ...
                }
            ]
        }
    ]
}

Conclusion

In this tutorial, we have covered the steps necessary to retrieve a user's aggregated financial information using Trustly's Account Summary API. We covered integrating the Trustly UI to create an authorized transaction and retrieving account summary data. With this information, you can begin to build powerful financial applications that leverage Trustly's advanced technology to offer better insights into your users' financial lives.

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 supporting Micro Challenge Deposits or adding additional user data to your Trustly integration for added benefits.