Akahu Setup

What is Akahu?

Akahu is a New Zealand open banking aggregator accredited by Payments NZ. It provides secure, read-only access to your bank accounts and transaction history. FFFFinance uses Akahu as its sole bank data source.

Prerequisites

• An Akahu account (sign up at akahu.nz)
• A personal app created at my.akahu.nz/developers
• Your bank accounts connected through Akahu's portal

Step-by-step setup

1. Sign up at akahu.nz and verify your identity.
2. Go to my.akahu.nz/developers and Create Personal App.
3. Connect your bank accounts within Akahu's portal (you authenticate directly with your bank).
4. Copy your App Token and User Access Token from the developer dashboard.
5. In FFFFinance: Settings > Connections > paste both tokens > Sync.

How sync works

• Fetches accounts via GET /accounts
• Fetches transactions via GET /transactions (cursor-based pagination, 100 per page)
• Default lookback: 2 years of transaction history
• Transactions are auto-categorized in a cascade:

User rules > Keyword patterns > Akahu NZFCC category > Uncategorized

Supported banks

ANZ, ASB, BNZ, Kiwibank, and Westpac are fully supported. Other NZ institutions connected through Akahu will also work.

Account types

Akahu account types are mapped to internal types:

Akahu type	Internal type
CHECKING	CHECKING
SAVINGS	SAVINGS
CREDITCARD	CREDIT
LOAN	CREDIT
INVESTMENT	INVESTMENT
KIWISAVER	INVESTMENT
FOREIGN_CURRENCY	CHECKING
REWARDS	REWARDS

Token storage and security

• Tokens are stored in the local SQLite settings table on your machine.
• Tokens are never transmitted anywhere except directly to Akahu's API (https://api.akahu.io/v1).
• API requests use two headers:

Authorization: Bearer {userToken}
X-Akahu-ID: {appToken}

• No data leaves your device unless you explicitly enable cloud sync (Cloudflare D1).

Auto-categorization

FFFFinance runs 12 NZ-specific keyword pattern groups against transaction descriptions:

Category	Example keywords
Salary	salary, wages, payroll, pay credit
Groceries	Countdown, New World, Pak'nSave, Fresh Choice, Four Square
Dining	McDonalds, KFC, Subway, Dominos, Hell Pizza, Burger King
Fuel	Z Energy, Gull, BP, Mobil, Caltex
Transport	AT HOP, Uber, taxi, parking, Waka Kotahi
Subscriptions	Netflix, Spotify, Apple, Google, Microsoft, Amazon Prime, Neon
Utilities	Genesis, Contact Energy, Meridian, Mercury, Vector, Watercare
Internet	Spark, Vodafone, One NZ, 2degrees, Orcon, Skinny
Health	pharmacy, doctor, medical, dental, physio, Southern Cross
Insurance	AIA, State Insurance, AA Insurance, Tower Insurance
Shopping	Trade Me, Amazon, Warehouse, Kmart, Farmers, Briscoes, Bunnings
Rent	rent, body corp, property management

If no keyword pattern matches, FFFFinance falls back to Akahu's NZFCC (NZ Financial Category Code) category when available. User corrections are learned and applied to future transactions.

Merchant logos

Merchant logos are resolved in a three-tier cascade:

1. Akahu merchant logo (transaction.merchant.logo) -- highest priority
2. Akahu meta logo (transaction.meta.logo) -- fallback from Akahu metadata
3. Local pattern matching -- built-in lookup table mapping merchant names and descriptions to known logos