ReportTransaction

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-report-transaction-schema.json",
  "title": "ReportTransaction",
  "description": "A record of money moving into or out of an account.",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-apply-api-openapi.yml#/components/schemas/ReportTransaction",
  "type": "object",
  "properties": {
    "_id": {
      "$ref": "#/$defs/ReportTransactionId"
    },
    "_account": {
      "allOf": [
        {
          "$ref": "#/$defs/ReportAccountId"
        },
        {
          "type": "string"
        }
      ]
    },
    "_source": {
      "type": "string",
      "description": "The data source that this transaction belongs to."
    },
    "action": {
      "$ref": "#/$defs/TransactionAction"
    },
    "type": {
      "$ref": "#/$defs/TransactionType"
    },
    "date": {
      "type": "string",
      "format": "date-time"
    },
    "description": {
      "type": "string"
    },
    "amount": {
      "type": "number",
      "description": "The transaction amount. Debits are returned as negative numbers."
    },
    "balance": {
      "type": [
        "number",
        "null"
      ],
      "description": "The account balance at this transaction, if available in the data source."
    },
    "merchant": {
      "$ref": "#/$defs/ReportMerchant"
    },
    "nzfcc": {
      "$ref": "#/$defs/TransactionCategory"
    },
    "income_category": {
      "anyOf": [
        {
          "$ref": "#/$defs/IncomeCategory"
        },
        {
          "type": "null"
        }
      ]
    },
    "spending_category": {
      "anyOf": [
        {
          "$ref": "#/$defs/SpendingCategory"
        },
        {
          "type": "null"
        }
      ]
    },
    "other_account": {
      "type": [
        "string",
        "null"
      ],
      "description": "The NZ account number of the other party to this transaction, if available."
    },
    "other_loan_account": {
      "type": [
        "string",
        "null"
      ],
      "description": "The loan account number of the other party to this transaction, if available."
    },
    "other_card_suffix": {
      "type": [
        "string",
        "null"
      ],
      "description": "The suffix of the card account for the other party to this transaction, if available."
    }
  },
  "required": [
    "_id",
    "_account",
    "_source",
    "action",
    "type",
    "date",
    "description",
    "amount",
    "balance",
    "merchant",
    "nzfcc",
    "income_category",
    "spending_category"
  ],
  "$defs": {
    "IncomeCategory": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "pattern": "^income:[0-9]{3}/[a-z0-9-]*$",
          "description": "A unique code for this income category."
        },
        "name": {
          "type": "string",
          "description": "The name of this income category."
        }
      },
      "required": [
        "code",
        "name"
      ],
      "description": "The income category for this transaction"
    },
    "MerchantId": {
      "type": "string",
      "pattern": "^merchant_[a-z0-9]{24,27}$"
    },
    "NZFCCategoryId": {
      "type": "string",
      "pattern": "^nzfcc_[a-z0-9]{24,27}$"
    },
    "ReportAccountId": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^report_acc_[a-z0-9]{24,27}$"
    },
    "ReportMerchant": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "_id": {
          "$ref": "#/$defs/MerchantId"
        },
        "name": {
          "type": "string"
        },
        "logo": {
          "type": "string",
          "description": "A URL pointing to a logo for this merchant."
        }
      },
      "required": [
        "_id",
        "name",
        "logo"
      ]
    },
    "ReportTransactionId": {
      "type": "string",
      "pattern": "^report_trans_[a-z0-9]{24,27}$"
    },
    "SpendingCategory": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "pattern": "^spending:[0-9]{3}/[a-z0-9-]*$",
          "description": "A unique code for this spending category."
        },
        "name": {
          "type": "string",
          "description": "The name of this spending category."
        }
      },
      "required": [
        "code",
        "name"
      ],
      "description": "The high-level spending category for this transaction."
    },
    "TransactionAction": {
      "type": "string",
      "enum": [
        "money_in",
        "money_out",
        "transfer"
      ],
      "description": "The net action of this transaction:\n\n - `money_in`: The transaction describes the inwards flow of funds (i.e. income).\n\n - `money_out`: The transaction describes the outwards flow of funds (i.e. an expense).\n\n - `transfer`: The transaction describes the transfer of funds between two accounts that are both present in the dataset provided for this report."
    },
    "TransactionCategory": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "_id": {
          "$ref": "#/$defs/NZFCCategoryId"
        },
        "name": {
          "type": "string"
        }
      },
      "required": [
        "_id",
        "name"
      ],
      "description": "A low-level NZFCC category for this transaction. See nzfcc.org"
    },
    "TransactionType": {
      "type": "string",
      "enum": [
        "CARD",
        "PAYMENT",
        "TRANSFER",
        "INTEREST",
        "FEE",
        "TAX",
        "DIRECT CREDIT",
        "DIRECT DEBIT",
        "STANDING ORDER",
        "ATM",
        "FX",
        "LOAN",
        "KIWISAVER",
        "CREDIT",
        "DEBIT",
        "UNKNOWN"
      ],
      "description": "The type of transaction:\n\n - `CARD` The transaction was initiated via Credit, Debit, or EFTPOS card.\n\n - `PAYMENT` An outbound payment to another New Zealand bank account.\n\n - `TRANSFER` A money transfer between two of the user's accounts with this provider.\n\n - `INTEREST` Interest received from a savings or investment account.\n\n - `FEE` Fee paid to the institution e.g. an account fee, card fee, ATM fee.\n\n - `TAX` Tax paid on interest or other source of income.\n\n - `DIRECT CREDIT` Payment received from another party.\n\n - `DIRECT DEBIT` Direct debit payment initiated by (and paid to) a third party with prior authorization from the account holder.\n\n - `STANDING ORDER` A regular scheduled payment, aka. 'Automatic payment'.\n\n - `ATM` ATM deposit or withdrawal.\n\n - `FX` Foreign currency exchange.\n\n - `LOAN` Payments towards a loan.\n\n - `KIWISAVER` Transactions towards a KiwiSaver account.\n\n - `CREDIT` A fallback for any other money that has entered the account.\n\n - `DEBIT` A fallback for any other money that has left the account.\n\n - `UNKNOWN` An unknown transaction type.\n"
    }
  }
}