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. Akahu can provide transaction data from connected accounts for all bank integrations and a selection of non-bank integrations. See the Supported Integrations reference for the full list of integrations that have transaction data available.

In addition to the basic transaction data that Akahu retrieves from the connected institution (such as date, amount, description), Akahu enriches transactions with merchant and categorisation data where possible. More information on enrichment data is provided in detail in this document.

Transaction data is only available to apps with the TRANSACTIONS scope. In addition, further permissions are required to access enriched transaction data. Personal apps have full access to enriched transactions by default. If you have a full Akahu app and would like access to transaction data, get in touch via [email protected] or our Slack workspace.

See our Accessing Transactional Data guide to learn how to retrieve 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 retrieved 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 retrieved 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.

description

The transacton 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"
}

meta

This is other metadata that we extract from the transaction, including the following fields (where possible). All of the meta fields are optional:

{
  // 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?