External asset connector¶


ID	`MOD-100`
System	SD07
Repo	`bank-platform`
Build status	Deployed
Deployed	Yes
Last commit	`bbdfbac46a1b5cf6dc25b4c7cd428a8daa669d03`

Purpose¶

Connects to external financial data providers — primarily Akahu (NZ) and direct AU superannuation fund APIs — to retrieve a customer's external asset data under explicit OAuth 2.0 consent. Normalises provider-specific response shapes into the canonical assets and asset_party_relationships schema in SD01 Postgres, making external assets visible to the wealth intelligence engine and the app net worth dashboard.

External assets currently in scope: - KiwiSaver accounts (NZ) — balance, fund type (conservative/balanced/growth/aggressive), provider name, last contribution date - AU superannuation (Phase 2) — balance, fund name, member number, last contribution date - Held-away bank accounts (optional) — balances at other NZ banks via Akahu (useful for bank migration UX)

Architecture¶

Akahu connection is a scheduled Lambda (daily, off-peak) that: 1. Fetches the list of consenting customers with valid Akahu tokens from operating_contexts.akahu_consent 2. For each customer, calls the Akahu /accounts and /balances endpoints 3. Maps the response to the assets schema (asset_type = 'KIWISAVER' or 'SUPERANNUATION' or 'EXTERNAL_DEPOSIT') 4. Writes normalised records into a staging table in SD07 Snowflake (FR-402); a write-back Lambda then upserts from the staging table into SD01 Postgres assets + asset_party_relationships 5. Fires bank-platform.external_asset_updated on EventBridge with customer_id, asset_id, asset_type, provider_name, balance_nzd (or balance_aud), as_at — emitted after the Postgres upsert succeeds

The normalisation layer is provider-agnostic: adding a new Akahu-connected provider requires only a mapping configuration entry, not code changes.

Customer consent is initiated from the app (MOD-075 external account linking flow). The Akahu OAuth flow redirects through the provider's consent screen. On completion, the Akahu consent token is stored in operating_contexts.akahu_consent with scope, expiry, and audit timestamp.

Consent is revocable at any time from the app. Revocation triggers immediate halt of retrieval and deletion of cached asset records within 24 hours (Privacy Act 2020 s 22 — retention only as long as purpose requires).

Data staleness¶

KiwiSaver unit prices are published each business day by fund managers. Retrieval runs daily at 02:00 NZST. The assets.last_refreshed_at timestamp is surfaced in the app so customers see when the balance was last updated. The UX explicitly labels these as "as at [date]" — not live.

If retrieval fails for a customer three consecutive days, a bank-app.external_asset_retrieval_failed alert is fired and a push notification prompts the customer to re-authorise.

Compliance notes¶

This module retrieves data under customer consent — not under the bank's own authority. The bank acts as a data recipient, not a data holder, for external assets. Privacy Act 2020 s 22 (use limitation) applies: data is used only for the purpose consented to (financial position display and wealth insights).

The module does not make any investment recommendations. It surfaces factual data (balance, fund type, contribution history) only.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-009	eIDV & document verification	Required	`contract/api/`	Customer identity verification required before Akahu consent flow can be initiated — unverified customers cannot link external accounts.
MOD-045	Secrets & key management	Required	—	Akahu API credentials and AU super provider keys are stored in Secrets Manager and rotated via the secrets management module.
MOD-042	CDC pipeline — Neon logical replication to S3 Iceberg	Optional	—	CDC pipeline propagates updated asset records to Snowflake for wealth intelligence engine consumption; not required for the write-back itself.
MOD-104	AWS shared infrastructure bootstrap	Required	—	AWS shared infrastructure provisioned by MOD-104 (EventBridge buses, S3, KMS, Kinesis, Cognito) is required before this module can be deployed.

Required by¶

Module	Title	As	Contract
MOD-101	Wealth intelligence engine	Hard dependency	—

Policies satisfied¶

Policy	Title	Mode	How
PRI-001	Privacy Policy	`LOG`	Akahu consent token, scope, and expiry recorded per customer — consent audit trail maintained for Privacy Act 2020 compliance.
PRI-003	Personal Information Retention & Destruction Policy	`GATE`	External asset retrieval halts immediately on consent revocation and cached records are deleted within 24 hours — no data retained beyond consent scope.

Capabilities satisfied¶

Capability	Title	Mode	How
CAP-141	CAP-141	`AUTO`	Polls Akahu daily for KiwiSaver and held-away account data under customer consent and normalises results into the assets schema without manual intervention.

Part of SD07 — Data Platform & Governance Infrastructure Compiled 2026-05-22 from source/entities/modules/MOD-100.yaml