Transaction_2

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-transaction-2-schema.json",
  "title": "Transaction_2",
  "x-generated": "2026-10-26",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-transactions-api-openapi.yml#/components/schemas/Transaction_2",
  "type": "object",
  "required": [
    "_id",
    "_account",
    "_connection",
    "date",
    "description",
    "type",
    "amount"
  ],
  "properties": {
    "_id": {
      "type": "string",
      "description": "The unique identifier for this transaction"
    },
    "_account": {
      "type": "string",
      "description": "The Account ID to identify which account this transaction belongs to"
    },
    "_connection": {
      "type": "string",
      "description": "The Connection ID to identify which institution this transaction was retrieved from."
    },
    "date": {
      "type": "string",
      "format": "date-time",
      "description": "The ISO 8601 timestamp of when this transaction was lodged by the bank"
    },
    "description": {
      "type": "string",
      "description": "The raw transaction description, essentially what you see on a bank statement"
    },
    "type": {
      "$ref": "#/$defs/TransactionType_2"
    },
    "amount": {
      "type": "number",
      "description": "The amount of money being debited or credited by this transaction. A negative value represents a debit and positive value a credit."
    },
    "balance": {
      "type": [
        "number",
        "null"
      ],
      "description": "The account balance after the receipt of this transaction, where available"
    },
    "meta": {
      "type": "object",
      "description": "Additional metadata that Akahu has extracted from the transaction. Availability of this metadata varies greatly depending on the institution that the transaction was sourced from and the transaction type. Please note that **all metadata items are optional**.",
      "properties": {
        "conversion": {
          "type": "object",
          "description": "Currency conversion information for payments that have been converted to a foreign currency. All fields are optional except `currency`.",
          "properties": {
            "currency": {
              "type": "string",
              "description": "The 3 digit currency code identifying the foreign currency involved in the conversion."
            },
            "amount": {
              "type": "number",
              "description": "The amount of foreign currency involved in this transaction."
            },
            "rate": {
              "type": "number",
              "description": "The currency conversion rate."
            },
            "fee": {
              "type": "number",
              "description": "The amount of any currency conversion fee associated with the transaction."
            }
          }
        },
        "card": {
          "type": "string",
          "description": "Partial card number associated with this transaction. This is generally the last 4 digits and may relate to a debit, credit, or EFTPOS card."
        },
        "other_account": {
          "type": "string",
          "description": "If the transaction involves money transfer to/from another New Zealand bank account, this field may contain the account number associated with the other account. Transactions that may have this data available include: `PAYMENT`, `TRANSFER`, `STANDING ORDER`, `DIRECT DEBIT`, `DIRECT CREDIT`."
        }
      }
    },
    "enrichment": {
      "type": "object",
      "required": [
        "category",
        "confidence"
      ],
      "properties": {
        "category": {
          "type": "object",
          "description": "The base NZFCC category that the transaction belongs to. Also included is a map of less specific category groupings that this NZFCC category is part of (by default Akahu will include `personal_finance`). Custom category groupings can be configured for your application if required.",
          "required": [
            "_id",
            "name",
            "groups"
          ],
          "properties": {
            "_id": {
              "type": "string",
              "description": "The NZFCC Category ID"
            },
            "name": {
              "type": "string",
              "description": "The NZFCC Category Name"
            },
            "components": {
              "type": "array",
              "deprecated": true,
              "items": {
                "type": "object",
                "description": "A category that this transaction falls under",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The category name"
                  },
                  "type": {
                    "type": "string",
                    "description": "The category set that this category comes from"
                  }
                }
              }
            },
            "groups": {
              "type": "object",
              "description": "Higher level groupings that this category belongs to.",
              "additionalProperties": {
                "type": "object",
                "required": [
                  "_id",
                  "name"
                ],
                "properties": {
                  "_id": {
                    "type": "string",
                    "description": "The ID for this group of categories"
                  },
                  "name": {
                    "type": "string",
                    "description": "The name of this group of categories"
                  }
                }
              }
            }
          }
        },
        "merchant": {
          "type": "object",
          "description": "The merchant that the transaction is paying to.",
          "required": [
            "_id",
            "name"
          ],
          "properties": {
            "_id": {
              "type": "string",
              "description": "The Akahu Merchant ID"
            },
            "name": {
              "type": "string",
              "description": "The merchant name"
            },
            "logo": {
              "type": "string",
              "format": "url",
              "description": "URL of a .png image of the merchant logo. If no logo is available, a placeholder image is provided."
            },
            "website": {
              "type": "string",
              "format": "uri",
              "description": "The Akahu Merchant website"
            }
          }
        },
        "confidence": {
          "type": "number",
          "description": "A score between `0` and `0.99` indicating Akahu's confidence in the enrichment accuracy. Currently the lowest returned confidence score is `0.5`. We are still tweaking the maths behind this score, but intend to release guidelines for usage once it becomes stable."
        }
      }
    }
  },
  "$defs": {
    "TransactionType_2": {
      "type": "string",
      "enum": [
        "CARD",
        "PAYMENT",
        "TRANSFER",
        "INTEREST",
        "FEE",
        "TAX",
        "DIRECT CREDIT",
        "DIRECT DEBIT",
        "STANDING ORDER",
        "ATM",
        "FX",
        "LOAN",
        "KIWISAVER",
        "CREDIT",
        "DEBIT",
        "UNKNOWN"
      ],
      "description": "Type of the transaction:\n\n  - `CARD` → The transaction was initiated via Credit, Debit, or EFTPOS card.\n  - `PAYMENT` → An outbound payment to another New Zealand bank account.\n  - `TRANSFER` → An internal money transfer between two accounts.\n  - `INTEREST` → Credits: Interest received from a savings or investment account. Debits: Interest charged on a debt (such as a loan, credit card, or overdraft).\n  - `FEE` → Fee paid to the institution e.g. an account fee, card fee, ATM fee.\n  - `TAX` → Tax paid on interest or other source of income.\n  - `DIRECT CREDIT` → Payment received from another party.\n  - `DIRECT DEBIT` → Direct debit payment initiated by (and paid to) a third party with prior authorization from the account holder.\n  - `STANDING ORDER` → Automatic payment.\n  - `ATM` → ATM deposit or withdrawal.\n  - `FX` → Foreign currency exchange.\n  - `LOAN` → Payments towards a loan.\n  - `KIWISAVER` → Transactions towards a KiwiSaver account.\n  - `CREDIT` → Money has entered the account (fallback).\n  - `DEBIT` → Money has left the account (fallback)."
    }
  }
}