ℹ️
This reference is intended for developers using Akahu's enduring account connectivity. Information provided may not be relevant for those using one-off account connectivity.

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. This value is direct from the bank and not modified by Akahu.

`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 withdrawal.
"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 granular NZFCC categories, Akahu also provides different levels of granularity in the form of category "groups". Currently Akahu offers the personal_finance group on all enriched transactions, which is suitable for constructing quick high level dashboards and overviews. Custom or bespoke category groupings can be configured for your application if required.

Categories are provided in the following format:

"category": {
  "_id": "nzfcc_1111111111111111111111111", // ID related to the NZFCC category
  "name": "Cafes & Restaurants", // NZFCC Category name
  "groups": {
    "personal_finance": {
      "_id": "group_1111111111111111111111111", // ID of this group
      "name": "Lifestyle" // Group name
    }
    // Any bespoke groupings will appear as additional entries
  }
}

`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, an optional website, and a merchant _id:

{
  "_id": "merchant_1111111111111111111111111",
  "name": "The Warehouse",
  "website": "https://www.thewarehouse.co.nz/"
}

`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
  },

  // If this transaction was made with a credit or debit card, we may be able to extract the
  // card number used to make the transaction.
  "card_suffix": "1234",

  // A URL pointing to an image for this transaction. This is typically the logo of the transaction merchant.
  "logo": "https://static.akahu.io/outlets/merchant_cjgkhyhvg000001n31lpr1zkt_logo.png",
}