The Transaction Model

The lowdown on how transactions are structured and what each key means.

What is a Transaction?

A transaction is a record of money moving between two accounts. In addition to the basic data that Akahu retreives from the bank, Akahu also enriches transactions with more relevant information. This page describes what sorts of information might be available about each transaction.

Keep in mind that you will only be able to see transactions if you have the required app and user permissions. In addition to this you require extra permissions to see the enriched data about each transaction.

See our Accessing Transactional Data guide to learn how to retreive transactions from Akahu's API.

Basic Transaction Data

This is what a basic transaction looks like, without any additional enrichment. It is essentially a standardised view of the transaction data Akahu gets from the bank.

_id

The _id key is a unique identifier for the transaction in the Akahu system. It is always be prefixed by trans_ so that you can tell that it refers to a transaction.

_account

The _account key indicates which account this transaction belongs to. See our guide to Accessing Account Data to learn how to get this account, and our Account Model docs to learn more about accounts.

_connection

This is the ID of provider that Akahu has retreived this transaction from. You can get a list of connections from our /connections endpoint.

created_at

The time that Akahu first saw this transaction (as an ISO 8601 timestamp). This is unrelated to the transaction date (when the transaction occurred) because Akahu may have retreived an old transaction.

date

The date that the transaction was posted with the account holder, as an ISO 8601 timestamp. In many cases this will only be accurate to the day, due to the level of detail provided by the bank. In this case the timestamp will be set to the start of that day (midnight the night before the transaction).

description

The transaction description as provided by the bank. Some minor cleanup is done by Akahu (such as whitespace normalisation), but this value is otherwise direct from the bank.

amount

The amount of money that was moved by this transaction.

balance

If available, the account balance immediately after this transaction was made.

type

What sort of transaction this is. Akahu tries to find a specific transaction type, falling back to "CREDIT" or "DEBIT" if nothing else is available.

The type will be one of:

  • "CREDIT" Money has entered the account.
  • "DEBIT" Money has left the account.
  • "PAYMENT" A payment to an external account.
  • "TRANSFER" A transfer between accounts that are associated with the same credentials.
  • "STANDING ORDER" An automatic payment.
  • "EFTPOS" A payment made via the EFTPOS system.
  • "INTEREST" An interest payment from the account provider.
  • "FEE" A fee from the account provider.
  • "TAX" A tax payment.
  • "CREDIT CARD" A credit card payment.
  • "DIRECT DEBIT" A direct debit payment.
  • "DIRECT CREDIT" A direct credit (someone paying into the account).
  • "ATM" An ATM deposit or withdrawl.
  • "LOAN" A payment related to a loan.

Enriched Transaction Data

This is data added by the Akahu enrichment engine. You must have additional permissions to view this data.

category

The category object categorises the transaction using NZFCC codes (New Zealand Financial Category Codes). As well as the most granular nzfcc:base categories, Akahu also provides several different levels of granuality, like the broader nzfcc:pfm category suitable for dashboards and overviews. Akaku can also support custom category sets which get mapped to the nzfcc:base categories.

Categories are provided in the following format:

"category": {
  "_id": "nzfcc_1111111111111111111111111", // ID related to the "nzfcc:base" category
  "components": [
    {
      "name": "Fast food restaurants",
      "type": "nzfcc:base" // The most granular level of categorisation
    },
    {
      "name": "Cafes & Restaurants",
      "type": "nzfcc:group" // A slightly less granular level of categorisation
    },
    {
      "name": "Lifestyle",
      "type": "nzfcc:pfm" // A broad level of categorisation
    }
  ]
}

merchant

Akahu defines a merchant as the business who was party to this transaction. For example, "The Warehouse" is a merchant.

Merchant data is provided as a name and a merchant _id:

{
  "_id": "merchant_1111111111111111111111111",
  "name": "The Warehouse"
}

outlet

Akahu defines the outlet as the specific premises that the transaction was made at. For example, "The Warehouse, Invercargill" is an outlet, and is distinct from "The Warehouse, Glenfield".

Outlet data is provided in the following format:

{
  "_id": "outlet_1111111111111111111111111",
  "name": "Bob's Pizza",
  "location": {
    "address": {
      "complete": "Matakana 0985, New Zealand",
      "country": "NZ",
      "locality": "Matakana",
      "postal_code": "0985"
    },
    "coordinates": {
      "lat": -36.351973,
      "lon": 174.717439
    },
    "pretty": "Matakana Valley Road, Matakana" // A pretty form of the address suitable for display
  }
}

meta

This is other metadata that we extract from the transaction, including the following fields (where possible):

{
  // Fields that are entered when a payment is made
  "particulars": "...",
  "code": "...",
  "reference": "...",

  // The formatted NZ bank account number of the other party to this transaction
  "other_account": "00-0000-0000000-00",

  // If this transaction was made in another currency, details about the currency conversion
  // This is an example conversion for a payment of Β£2.15 GBP:
  "conversion": {
    "amount": 2.15,
    "currency": "GBP",
    "rate": 0.49
  }
}

Did this page help you?