Teller operations and branch cash management¶


ID	`MOD-129`
System	SD08
Repo	`bank-app`
Build status	Not started
Deployed	No

Purpose¶

Provides a teller workstation mode for branch staff to process over-the-counter cash transactions on behalf of customers. Covers cash deposits, cash withdrawals, and branch cash drawer management. Designed for community banks and building societies that operate physical branches as a service channel alongside the digital app.

Scope¶

This module is limited to domestically-denominated cash transactions. Not in scope: foreign currency exchange, traveller's cheques, or money order issuance. (All NZ Big 4 banks have exited international cash services; this is not a standard teller function at any NZ bank and is not a reasonable expectation for a building society or small community bank deploying this platform.)

Teller role context¶

The module introduces a dedicated teller JWT role. Staff with this role access the teller workstation — a focused back-office UI separate from the standard back-office panel — which presents only the controls relevant to in-branch transactions. The teller's session is bound to a branch code and cash drawer ID. All postings made during a teller session carry the teller's staff_id, the branch_code, and the drawer_id in the posting metadata.

Tellers can: - Search for customer accounts by customer ID, account number, or verified identity document. - Post cash deposits and cash withdrawals to customer accounts. - Trigger a KYC identity check via MOD-009 for customers without a card, or for transactions requiring enhanced identity verification. - Open and close their cash drawer session with opening/closing balance reconciliation. - Record a cash drawer variance with a reason note.

Tellers cannot: - Override pre-payment validation (balance, sanctions, account status). - Modify customer records. - Access credit decision functions. - Process transactions outside their authorised cash limit without supervisor override (configurable per branch).

AML reporting¶

Cash transactions above the prescribed reporting threshold trigger the AML cash transaction reporting workflow. Thresholds are jurisdiction-specific:

NZ: NZD 10,000 or equivalent — required reporting to the Police Financial Intelligence Unit under the AML/CFT Act 2009, s.48.
AU: AUD 10,000 or equivalent — required Threshold Transaction Report (TTR) to AUSTRAC under the AML/CTF Act 2006, s.43.

The threshold check runs automatically at the point of teller confirmation. When triggered: the teller is prompted to confirm the customer's identity (MOD-009 verification or document inspection), the transaction is flagged as ctr_required, and the cash transaction report is queued for submission via the AML monitoring module. The posting is not finalised until the identity confirmation is recorded.

Structuring detection — multiple transactions below the threshold that together appear designed to avoid reporting — is handled by the AML monitoring platform (MOD-034, SD03), not by this module. MOD-129 provides the raw transaction data; MOD-034 identifies structuring patterns.

Data model¶

-- app.teller_sessions
CREATE TABLE app.teller_sessions (
  session_id       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  staff_id         UUID NOT NULL,
  branch_code      TEXT NOT NULL,
  drawer_id        TEXT NOT NULL,
  opened_at        TIMESTAMPTZ NOT NULL DEFAULT now(),
  opening_balance  NUMERIC(18,2) NOT NULL,
  closed_at        TIMESTAMPTZ,
  closing_balance  NUMERIC(18,2),
  expected_balance NUMERIC(18,2),  -- calculated from transactions
  variance         NUMERIC(18,2),  -- closing_balance - expected_balance
  variance_reason  TEXT,
  status           TEXT NOT NULL DEFAULT 'open' CHECK (status IN ('open','closed','variance_noted'))
);

-- app.teller_transactions
CREATE TABLE app.teller_transactions (
  teller_tx_id     UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  session_id       UUID NOT NULL REFERENCES app.teller_sessions(session_id),
  account_id       UUID NOT NULL,
  transaction_type TEXT NOT NULL CHECK (transaction_type IN ('cash_deposit','cash_withdrawal')),
  amount           NUMERIC(18,2) NOT NULL,
  currency         TEXT NOT NULL DEFAULT 'NZD',
  ctr_required     BOOLEAN NOT NULL DEFAULT false,
  identity_method  TEXT CHECK (identity_method IN ('card','document_inspection','eidv')),
  posting_id       UUID,  -- MOD-001 posting reference
  staff_id         UUID NOT NULL,
  branch_code      TEXT NOT NULL,
  created_at       TIMESTAMPTZ NOT NULL DEFAULT now()
);

Key operations¶

Cash deposit¶

The teller searches for the customer's account, enters the cash amount, confirms the notes and coins tendered, and submits. Pre-payment validation runs (account status, sanctions screen). On validation pass: the deposit is posted via MOD-001 as a debit to the branch cash account and a credit to the customer's account. The customer's available balance is updated immediately. The teller transaction record is created and linked to the MOD-001 posting. The teller's session expected balance increases by the deposit amount.

If the amount meets or exceeds the AML reporting threshold, the identity confirmation step is inserted before the posting is finalised.

Cash withdrawal¶

The teller enters the withdrawal amount. MOD-003 is called to confirm available balance. If sufficient: pre-payment validation runs. On pass: the withdrawal is posted via MOD-001. The customer's available balance is reduced. The teller's session expected balance decreases.

If the amount meets or exceeds the AML reporting threshold, the identity confirmation step runs before the withdrawal can be authorised.

Supervisor override¶

Cash withdrawals above a configurable per-session limit require supervisor authorisation. The teller submits a supervisor override request; a back-office supervisor approves from their own authenticated session. The override approval is recorded alongside the teller transaction. This control is configurable per branch, allowing institutions with higher-trust environments to raise the threshold.

Session close¶

At end of day (or end of shift), the teller counts their drawer and enters the physical closing balance. The system calculates the expected balance from all transactions in the session. If variance > configured_tolerance, status = variance_noted and the teller must record a variance reason. The session record, all transactions, and any variance note are passed to MOD-081 for branch reconciliation.

Requirements¶

FR-581 — Teller identity binding: every teller posting must carry the teller's staff_id, branch_code, and drawer_id in the posting metadata recorded in MOD-001; no teller posting may be made without an active teller session; the teller identity must be immutable on the posting record after confirmation.

FR-582 — AML threshold gate: any cash transaction at or above the jurisdiction-specific reporting threshold must trigger the identity confirmation step before the posting is finalised; the ctr_required flag must be set on the teller transaction record; the posting must not proceed until a valid identity method is recorded.

FR-583 — Pre-payment validation: all teller-initiated cash withdrawals must pass the same pre-payment validation checks (available balance via MOD-003, account status, sanctions screen) as digital channel payments; no teller bypass path may exist that authorises a withdrawal when validation would return a decline for the same transaction from the digital channel.

FR-584 — Session reconciliation: on session close, the system must calculate expected_balance from the sum of all transactions in the session, compare it to the teller-entered closing_balance, and record any variance; sessions with a variance outside the configured tolerance must be flagged to the branch operations queue and must not be closed without a variance reason being recorded.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-001	Double-entry posting engine	Required	—	All teller cash postings (deposits, withdrawals) are executed via the double-entry engine with the teller's staff ID recorded in the posting metadata.
MOD-003	Real-time balance engine	Required	—	Available balance is checked before authorising a cash withdrawal — the teller workstation displays the real-time available balance drawn from the balance engine.
MOD-009	eIDV & document verification	Optional	—	The teller can trigger an eIDV check for identity verification at point of service, required for large cash transactions or when a customer cannot produce a card.
MOD-047	Agent action logger	Required	—	All teller actions — including declined transactions, identity checks, and cash drawer adjustments — are logged to the agent action audit trail with the teller's staff ID.
MOD-081	Payment reconciliation engine	Required	—	Branch end-of-day cash figures are reconciled against teller session totals via the payment reconciliation engine to detect any cash drawer variances.

Required by¶

(No modules in this wiki currently declare a dependency on this module.)

Policies satisfied¶

Policy	Title	Mode	How
AML-005	Transaction Monitoring Policy	`GATE`	Cash transactions above the prescribed reporting threshold require teller-initiated identity verification and are automatically submitted to the cash transaction reporting workflow before the posting is finalised.
PAY-001	Payment Operations Policy	`GATE`	All teller-initiated postings pass the same pre-payment validation (available balance, account status, sanctions screen) as digital channel payments — no teller bypass path exists.
GOV-006	Internal Audit Policy	`LOG`	Every teller transaction is logged with the teller's staff ID, branch code, session ID, and timestamp in addition to the standard transaction audit trail — the teller identity is immutably recorded at the database layer.
CON-001	Customer Fairness & Conduct Policy	`AUTO`	Cash receipts are posted and the customer's available balance is updated immediately upon teller confirmation — the customer's balance is never temporarily reduced or withheld pending a manual reconciliation step.

Capabilities satisfied¶

(No capabilities mapped)

Part of SD08 — Customer App & Back Office Platform Compiled 2026-05-22 from source/entities/modules/MOD-129.yaml