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 (looks like user_token_111111111111111111111111). Follow the Getting Started Guide to obtain one.
  • Your app access token (looks like app_token_111111111111111111111111). 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 header:

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

Where the {{user access token}} is replaced 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",
      "_category": "category_1111111111111111111111111",
      "created_at": "2020-01-01T12:00:00.000Z",
      "updated_at": "2020-01-01T12:00:00.000Z",
      "date": "2020-01-01T12:00:00.000Z",
      "pending": false,
      "raw": {
        "name": "***********",
        "description": "******************",
        "type": "debit"
      },
      "meta": {
        "currency": "NZD",
        "card": "xxxx",
        "card_present": "PRESENT"
      },
      "name": "********",
      "amount": -10.5,
      "type": "EFTPOS",
      "logo": "https://*******.jpg",
      "location": {
        "accuracy": "LOCALITY",
        "coordinates": {
          "lat": "**********",
          "lon": "**********"
        },
        "address": {
          "complete": "Auckland CBD, Auckland, New Zealand",
          "country": "New Zealand",
          "sublocality": "Auckland CBD",
          "locality": "Auckland",
          "postal_code": "1010"
        }
      }
    }
    ...
  ]
}

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.

Constants

Transaction type. When available, Akahu adds a specific transaction type from the following list:

  • CREDIT A generic account credit.
  • DEBIT A generic account debit.
  • PAYMENT A payment.
  • TRANSFER A transfer to another account.
  • STANDING ORDER An automatic payment.
  • EFTPOS An eftpos transaction.
  • INTEREST An interest credit or debit.
  • FEE An account fee.
  • CREDIT CARD A credit card transaction.
  • TAX A tax credit or debit.
  • DIRECT DEBIT A direct debit from your account.
  • DIRECT CREDIT A direct credit into your account.
  • ATM An ATM transaction.
  • LOAN A loan payment.

Transaction status. When you make a transaction with a credit card, it will often show up in your bank account as "Pending" for a few hours. Akahu exposes this with the item.pending field, which will be either true or false.

Card Presence. When you make an online payment with a credit or debit card, your card is not physically present. Akahu exposes this with the item.meta.card_present field, which will be either PRESENT, ABSENT, or UNKNOWN.

Location Accuracy. Akahu provides physical location information when possible. There are two primary types of locations, websites (given by item.location.url) and physical locations (given by item.location.address). When Akahu has a physical address, the accuracy of the location can vary. Akahu provides accuracy information in item.location.accuracy, ranging from most precise to least precise:

  • STREET_ADDRESS, eg. 27 Example St, Example Town, New Zealand
  • LOCALITY, eg. Auckland
  • COUNTRY, eg. New Zealand

Getting a Date Range

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, an ISO 8601 date-time string can also 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.

Conclusion

You should now be able to:

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