Joint account management

ID	MOD-125
System	SD01
Repo	bank-core
Build status	Deployed
Deployed	Yes
Last commit	2b41724

---

Purpose

Manages multi-party account ownership for joint accounts. Maintains the relationship between an account and each of its named holders, including signing authority configuration, individual KYC tracking per holder, balance apportionment for regulatory reporting (NZ DCS Single Depositor View), and the lifecycle events unique to joint accounts: holder death, holder removal, and holder addition.

Regulatory dimension — NZ Deposit Takers Act 2023 / Depositor Compensation Scheme

The NZ Depositor Compensation Scheme (DCS), live 1 July 2025, requires every NZ-licensed deposit taker to maintain a Single Depositor View (SDV) — a data file that aggregates each natural person's total insured deposits across all accounts. Joint accounts are protected per holder up to $100,000 per person.

The SDV file must apportion the joint account balance equally across all named holders unless the account agreement specifies otherwise. This means:

• Every holder must be individually identified as a natural person, not recorded as a single "joint account" entity.
• Each holder's share of the account balance must be calculable at any point in time.
• REP-007 must be able to sum each person's total deposits including their proportional share of all joint accounts they hold.

This is a prudential compliance requirement under the DTA, not solely an AML obligation. Non-compliance with the SDV requirement is a reportable breach to the Reserve Bank of NZ.

Signing authority model

Three modes are supported at the account level:

• any_one — any single holder can initiate and confirm transactions. Used for most personal joint accounts.
• all — all holders must authorise each transaction. Used for business and trust accounts with multiple required signatories.
• any_two — any two of N holders must authorise. Used for larger groups where all would be operationally impractical.

The signing authority mode is set at account opening and can be amended only with consent of all active holders. Changes are logged to joint_account_events.

Data model

-- core.account_holders
CREATE TABLE core.account_holders (
  holder_id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  account_id         UUID NOT NULL REFERENCES core.accounts(account_id),
  customer_id        UUID NOT NULL REFERENCES core.customers(customer_id),
  holder_type        TEXT NOT NULL CHECK (holder_type IN ('primary','joint','minor','trustee')),
  balance_share_pct  NUMERIC(5,2) NOT NULL DEFAULT 50.00,  -- for DCS/SDV apportionment
  signing_authority  TEXT NOT NULL DEFAULT 'any_one' CHECK (signing_authority IN ('any_one','all','any_two')),
  kyc_status         TEXT NOT NULL DEFAULT 'pending' CHECK (kyc_status IN ('pending','verified','failed')),
  consent_given      BOOLEAN NOT NULL DEFAULT false,
  consent_given_at   TIMESTAMPTZ,
  status             TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','deceased','removed')),
  added_at           TIMESTAMPTZ NOT NULL DEFAULT now(),
  removed_at         TIMESTAMPTZ
);

-- core.joint_account_events
CREATE TABLE core.joint_account_events (
  event_id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  account_id         UUID NOT NULL REFERENCES core.accounts(account_id),
  event_type         TEXT NOT NULL CHECK (event_type IN ('holder_added','holder_removed','holder_deceased','authority_changed','share_adjusted','account_closed')),
  initiated_by       UUID,  -- customer_id of the initiating holder or NULL for system events
  event_data         JSONB,
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now()
);

balance_share_pct values across all active holders for a given account must sum to 100.00. The application layer enforces this constraint; the database constraint enforces it per row.

Key operations

Joint account opening

The primary holder initiates account opening. Invited holder(s) receive a secure link via MOD-063 to complete their portion of the application. Each holder completes eIDV via MOD-009 independently — there is no shared or delegated identity step.

MOD-007 holds the account in pending_holders state until all required holders have:

1. Completed eIDV and received a KYC status of verified.
2. Provided individual consent via MOD-049.

The account activates to active only when all conditions are met across all holders. Invited holders have 14 days to complete. After that deadline, the primary holder is notified via MOD-063 and may re-issue the invitation.

Transaction authorisation

For any_one accounts: any holder's authenticated session can initiate and confirm transactions through the standard payment flow.

For all accounts: payment initiation creates a pending_authorisation record. All other holders receive a notification via MOD-063 and must approve via their own biometric session. The payment submits only when all required approvals are received. Requests expire after 24 hours if not fully approved; the initiating holder is notified on expiry.

For any_two accounts: the same pending authorisation flow applies, but the threshold is met when any two distinct holders have approved.

Death of a holder

A holder's death is notified by the estate or by a surviving holder. The module sets the deceased holder's status = deceased and records the notification date in joint_account_events. The account continues operating under the surviving holders' existing signing authority.

The deceased holder's balance_share_pct is frozen for estate administration. Surviving holders cannot transfer or redistribute the deceased holder's share until the estate provides legal documentation (death certificate and probate or letters of administration, stored via MOD-073). Once documentation is accepted by back-office review, the share can be redistributed or paid out to the estate.

DCS / SDV apportionment

balance_share_pct is set at account opening. The default for a two-holder account is 50.00% each. For SDV purposes, the holder's insured deposit contribution from this account is:

holder_insured_amount = account_balance × (balance_share_pct / 100)

REP-007 queries core.account_holders to aggregate each customer_id's total insured deposits across all accounts, including joint account shares. Non-default splits require written agreement from all holders at opening; the agreement is stored in MOD-073 and event_data on the share_adjusted event records the rationale.

Holder removal

Any active holder may request to be removed from a joint account. Removal requires consent of all remaining holders (or a court order). The module sets status = removed and removed_at for the departing holder, recalculates and distributes the departing holder's balance_share_pct equally among remaining holders (or as agreed), and logs a holder_removed event to joint_account_events. The account remains open for the remaining holders.

Holder addition

An existing holder may propose adding a new holder. All current active holders must consent. The new holder completes eIDV via MOD-009 and provides individual consent before they are activated. balance_share_pct values are renegotiated across all holders at the time of addition.

Requirements

FR-565 — Multi-party account activation: account must not activate until all required holders have individually completed eIDV and provided consent.

FR-566 — Signing authority enforcement: transaction authorisation flow must enforce the account's signing_authority mode; all and any_two modes must block submission until the required number of distinct holder approvals is recorded.

FR-567 — DCS SDV apportionment: balance_share_pct must be maintained per holder and queryable by REP-007 at any point in time; the sum of active holders' shares must equal 100.00.

FR-568 — Holder death workflow: on notification of a holder's death, the module must freeze the deceased holder's share and prevent redistribution until valid legal documentation is recorded in MOD-073.

---

Module dependencies

Depends on

Module	Title	Required?	Contract	Reason
MOD-001	Double-entry posting engine	Required	—	Joint account transactions are posted via the double-entry engine with the account as a single ledger entity — the joint holder model is in the account metadata layer, not the ledger.
MOD-009	eIDV & document verification	Required	—	Each joint account holder must complete eIDV independently before the account can open.
MOD-007	Account state machine	Required	—	The account state machine manages the multi-party activation sequence — account transitions to active only when all required holders have completed KYC and provided consent.
MOD-063	Notification orchestration	Required	—	Notifications relating to the account are dispatched to all joint holders via notification orchestration.

Required by

Module	Title	As	Contract
MOD-143	Open Bank Resolution pre-positioning	Hard dependency	—

---

Policies satisfied

Policy	Title	Mode	How
AML-002	Customer Due Diligence (CDD) Policy	GATE	All joint account holders must individually pass eIDV and CDD tier assignment before the account activates — partial KYC completion does not allow the account to open.
CON-001	Customer Fairness & Conduct Policy	AUTO	All joint account holders receive statements, notices, and communications simultaneously — no holder receives less information than any other.
PRI-001	Privacy Policy	AUTO	Each joint account holder's personal data is processed with individual consent; each holder has individual rights of access, correction, and portability over their own data.
REP-007	DCS & Depositor Reporting Policy	CALC	Each joint account holder's proportional share of the account balance is calculated and available for the Single Depositor View (SDV) file required under the NZ Depositor Compensation Scheme (DTA 2023).

---

Capabilities satisfied

(No capabilities mapped)

---

Part of SD01 — Core Banking Platform Compiled 2026-05-22 from source/entities/modules/MOD-125.yaml