Accessing Transactional Data

Transactional data is an enriched list of financial transactions the user has made. Akahu allows you to access this data on behalf of the user.

Prerequisites

Before you can follow this guide, you will need:

• To be able to make requests to the Akahu API (see here for instructions).
• A user access token (<<apiKey>>). Follow the Getting Started Guide to obtain one.
• Your app access token (<<appToken>>). You should get this when you create your app.
• An Akahu account with at least one account connected. This account must have transactions, preferably a few so that you can practice filtering them in different ways.

To determine if your account has transactions, make a GET request to the /accounts endpoint.
Locate your account in the results and look for the attributes key. If your account attributes include TRANSACTIONS, then the account has transactions.

Making the Request

API Reference

Using your language of choice, make a GET request to the https://api.akahu.io/v1/transactions endpoint, with the following headers:

Authorization: Bearer {{user access token}}
X-Akahu-ID: {{app access token}}

Replace the {{user access token}} with your user access token, and {{app access token}} with your app access token.

Handling the response

As in Accessing Account Data, you should handle any HTTP error codes returned by the API.

The API response will look like:

{
  "success": true,
  "items": [
    {
      "_id": "trans_1111111111111111111111111",
      "_account": "acc_1111111111111111111111111",
      "_connection": "conn_1111111111111111111111111",
      "created_at": "2020-01-01T01:00:00.000Z",
      "updated_at": "2020-01-01T01:00:00.000Z",
      "date": "2020-01-01T00:00:00.000Z",
      "description": "{RAW TRANSACTION DESCRIPTION}",
      "amount": -5.5,
      "balance": 100,
      "type": "EFTPOS"
    }
    // ...
  ],
  "cursor": {
    "next": "abc123...321cba"
  }
}

Breaking down this response:

At the top level, the key success is true. That means that the request was successful.

The items key contains a list of Akahu Transactions, with various information. Different types of accounts have different levels of detail in their transactions, depending on what is available.

The cursor key allows you to paginate through the results. This allows you to efficiently get transactions for large time-spans, without having to handle gigabyte response sizes. See the section on Pagination below for more information on working with cursors.

Getting a Date Range

📘

Timezones

Akahu's API returns all dates and times in UTC. If no timezone is specified on timestamps in the request, Akahu will assume that the times are also UTC. See here to learn how to specify a timezone in a ISO 8601 date-time string.

By default, the API will return transactions from the last 30 days. If you want to retrieve data for a specific period, you can specify the start and end query parameters. These should be ISO 8601 formatted date strings, for example "2020-01-10" to specify the 10th of January 2020. If you require additional precision, a full ISO 8601 date-time string can be supplied.

Getting Transactions For a Single Account

By default, the API will return transactions from all accounts you have access to. To retrieve transactions from a single account, update the uri to https://api.akahu.io/v1/accounts/{_id}/transactions, where {_id} is replaced by the Akahu Account ID you wish to retrieve transactions for.

Enriched Data

If you have permission to view our enriched transactional data, you will see 3 additional fields on your transactions:

• outlet This is the specific outlet the transaction originated from, for example the Four Square in Matakana.
• merchant This is the parent company that own the outlet, for example Four Square.
• category This is what the transaction has been categorised as.

More detail about these enriched fields can be found in our Transaction Model Documentation

Pagination

For larger queries (those that have many transactions, or span long time-periods), you will probably not receive all transactions for your query at once. Instead, you may only receive the first "page" of results. If a response does not contain all transactions for the provided query, it will also include a "cursor" that points to the next page of results.

To access subsequent pages, simply take the cursor.next value from each response and make a new request, supplying this value using the cursor query parameter. In response, you will receive the next page of results, along with a new cursor.next value.

Once you have reached the final page of results, the value of cursor.next will be null. This means that all transactions that match your query have been returned. Passing this null cursor back to the API will result in an error response.

See below for an example taken from our Javascript SDK:

const query = {
  // start: "2021-01-01T00:00:00.000Z",
  // end: "2021-01-02T00:00:00.000Z",
};

const transactions = [];

do {
  // Transactions are returned one page at a time
  const page = await akahu.transactions.list(userToken, query);
  // Store the returned transaction `items` from each page
  transactions.push(...page.items);
  // Update the cursor to point to the next page
  query.cursor = page.cursor.next;
  // Continue until the server returns a null cursor
} while (query.cursor !== null);

Pending Transactions

Pending transactions are served from a separate endpoint, and contain less information than transactions that have been fully resolved. This is because NZ banks typically do not serve a consistent view of pending transactions (eg. the date and description often change). When working with pending transactions, it is recommended that you completely rebuild your local copy of this data (i.e. delete then re-create) each time you refresh it from this endpoint.

Conclusion

You should now be able to:

• Obtain recent user transactions
• Filter transactions by date
• Get transactions for a given account