Transaction

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/akahu/main/json-schema/akahu-transaction-schema.json",
  "title": "Transaction",
  "x-generated": "2026-10-27",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/akahu-enduring-api-openapi.yml#/components/schemas/Transaction",
  "type": "object",
  "required": [
    "_id",
    "_account",
    "_connection",
    "_user",
    "date",
    "description",
    "amount",
    "type",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "_id": {
      "type": "string",
      "description": "The Akahu Transaction ID"
    },
    "_account": {
      "type": "string",
      "description": "The Akahu Account ID that this transaction belongs to"
    },
    "_connection": {
      "type": "string",
      "description": "The Akahu Connection ID that this transaction belongs to"
    },
    "_user": {
      "type": "string",
      "description": "The Akahu User ID that this transaction belongs to"
    },
    "_migrated": {
      "type": "string",
      "description": "The Akahu Transaction ID that this transaction was migrated from."
    },
    "_migrated_account": {
      "type": "string",
      "description": "The Akahu Account ID that this transaction was migrated from."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "The ISO 8601 timestamp of when this transaction was retrieved and created by Akahu"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "The ISO 8601 timestamp of when this transaction was last updated by Akahu"
    },
    "date": {
      "type": "string",
      "format": "date-time",
      "description": "The ISO 8601 timestamp of when this transaction was created by the bank"
    },
    "description": {
      "type": "string",
      "description": "The raw transaction description, essentially what you see on a bank statement"
    },
    "amount": {
      "type": "number",
      "description": "How much money this transaction was for"
    },
    "balance": {
      "type": "number",
      "description": "The account balance after the receipt of this transaction, where available"
    },
    "type": {
      "$ref": "#/$defs/TransactionType"
    },
    "hash": {
      "type": "string",
      "description": "This field is deprecated and should not be used. It is scheduled to be removed in future API versions.",
      "deprecated": true
    },
    "merchant": {
      "type": "object",
      "description": "The merchant that generated this transaction. Only present when you have permission to view enriched transactions.",
      "properties": {
        "_id": {
          "type": "string",
          "description": "The Akahu Merchant ID"
        },
        "name": {
          "type": "string",
          "description": "The Akahu Merchant name"
        },
        "website": {
          "type": "string",
          "format": "uri",
          "description": "The Akahu Merchant website"
        }
      }
    },
    "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. Only present when you have permission to view enriched transactions.",
      "properties": {
        "_id": {
          "type": "string",
          "description": "The NZFCC Category ID"
        },
        "name": {
          "type": "string",
          "description": "The NZFCC Category Name"
        },
        "groups": {
          "$ref": "#/$defs/CategoryGroups"
        }
      }
    },
    "meta": {
      "type": "object",
      "description": "Additional metadata we manage to retrieve for the transaction. Only present when you have permission to view enriched transactions. All fields are optional and provided on a \"best-effort\" basis.",
      "properties": {
        "particulars": {
          "type": "string",
          "description": "The particulars field set on this transaction."
        },
        "code": {
          "type": "string",
          "description": "The code field set on this transaction."
        },
        "reference": {
          "type": "string",
          "description": "The reference field set on this transaction."
        },
        "other_account": {
          "type": "string",
          "description": "The formatted NZ bank account number of the other party to this transaction."
        },
        "conversion": {
          "type": "object",
          "description": "If this transaction was made in another currency, details about the currency conversion.",
          "properties": {
            "amount": {
              "type": "number",
              "description": "The amount transacted in the foreign currency"
            },
            "currency": {
              "type": "string",
              "description": "The (3 letter ISO 4217 currency code)[https://www.xe.com/iso4217.php] that was used for this transaction."
            },
            "rate": {
              "type": "number",
              "description": "The foreign currency conversion rate applied to this transaction."
            }
          }
        },
        "card_suffix": {
          "type": "string",
          "description": "If this transaction was made with a credit or debit card, the last four digits of the card number."
        },
        "logo": {
          "type": "string",
          "format": "uri",
          "description": "URL of an image for this transaction. This is typically the logo of the transaction merchant. If no logo is available, a placeholder image is provided."
        }
      }
    }
  },
  "$defs": {
    "CategoryGroups": {
      "type": "object",
      "description": "Higher level groupings that a category belongs to.",
      "additionalProperties": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "description": "The ID for this group of categories"
          },
          "name": {
            "type": "string",
            "description": "The name of this group of categories"
          }
        }
      }
    },
    "TransactionType": {
      "type": "string",
      "enum": [
        "CREDIT",
        "DEBIT",
        "PAYMENT",
        "TRANSFER",
        "STANDING ORDER",
        "EFTPOS",
        "INTEREST",
        "FEE",
        "TAX",
        "CREDIT CARD",
        "DIRECT CREDIT",
        "DIRECT DEBIT",
        "ATM",
        "LOAN"
      ],
      "description": "Type of the transaction:\n\n  - `CREDIT` → Money has entered the account.\n\n  - `DEBIT` → Money has left the account.\n\n  - `PAYMENT` → Payment to an external account.\n\n  - `TRANSFER` → Transfer between accounts that are associated with the same credentials.\n\n  - `STANDING ORDER` → Automatic payment.\n\n  - `EFTPOS` → Payment made via an EFTPOS system.\n\n  - `INTEREST` → An interest payment.\n\n  - `FEE` → Fee payment to the account provider.\n\n  - `TAX` → Tax payment.\n\n  - `CREDIT CARD` → Credit card payment.\n\n  - `DIRECT DEBIT` → Direct debit payment.\n\n  - `DIRECT CREDIT` → Direct credit (someone paying into the account).\n\n  - `ATM` → ATM deposit or withdrawal.\n\n  - `LOAN` → Loan payment."
    }
  }
}