Credit servicing & collections¶


ID	`MOD-065`
System	SD05
Repo	`bank-credit`
Build status	Deployed
Deployed	Yes
Last commit	`19b0610`

Credit servicing and collections covers the full post-origination lifecycle of a loan — from first repayment through to full settlement or, in adverse cases, default and write-off. This module fills the gap between loan approval (handled by MOD-029) and impairment provisioning (handled by MOD-031), managing the customer relationship and operational processes in between.

For customers in good standing, the module provides a repayment schedule view, payment date change capability, early repayment and settlement requests, and accurate running balance at any point in the loan term. For customers in arrears, it runs the collections workflow: automated reminders at configured intervals, escalation to the collections team, and hardship assessment when triggered.

The hardship flow is designed to meet regulatory obligations under the CCCFA (NZ) and NCCP (AU): customers can request relief through the app, the module evaluates eligibility against configured criteria, and approved restructures are journalled atomically so the loan balance and repayment schedule remain consistent with the ECL inputs in MOD-031.

v2 scope: hardship fee-waiver check endpoint¶

MOD-065 v2 will expose a synchronous fee-waiver check endpoint:

GET /hardship/fee-waiver-check?party_id=&fee_kind=
→ { waived: boolean, reason: string | null, arrangement_id: uuid | null }

This endpoint answers whether an active hardship arrangement covers a specific fee type for a given party. It will replace the v1 tactical bridge used by MOD-117 (overdraft) and any other fee-engine callers that currently read MOD-007's hardship flag directly.

v1 bridge (in force now): MOD-117 reads MOD-007's hardship-flag-read-url and waives all overdraft fees when the flag is set. This is the correct v1 behaviour — flagged = full waiver — because the v1 hardship arrangement does not have per-fee-kind terms. MOD-065 v2 adds the per-fee-kind granularity when product requirements call for it.

Trigger for v2: When a credit product is launched with a hardship arrangement that specifies fee-kind-level waiver conditions (e.g. "waive maintenance fees but not late payment fees"), the v2 endpoint becomes necessary. Until then, MOD-117's direct MOD-007 flag read is correct and sufficient.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-007	Account state machine	Required	—	Loan stage transitions (arrears, default, written-off) are applied through the account state machine.
MOD-031	ECL calculation & GL posting	Required	—	Stage transitions trigger ECL impairment events that the ECL calculation module must process.
MOD-001	Double-entry posting engine	Required	—	Hardship restructure and payment reversal entries are posted through the posting engine.
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.
MOD-103	Neon database platform bootstrap	Required	—	Neon database and schema provisioned by MOD-103 must exist before this module can read or write Postgres.

Required by¶

Module	Title	As	Contract
MOD-116	Mortgage servicing engine	Hard dependency	—
MOD-117	Overdraft management engine	Hard dependency	—
MOD-139	Financial hardship formal variation workflow	Optional enhancement	—

Policies satisfied¶

Policy	Title	Mode	How
CRE-006	Impairment & Provisioning Policy	`AUTO`	Tracks loan stage transitions (current → arrears → default) and triggers the impairment events that feed the ECL engine.
CON-003	Vulnerable Customer Policy	`AUTO`	Routes customers who meet hardship criteria into the hardship assessment workflow with appropriate communications triggered.
CRE-002	Responsible Lending Policy	`ALERT`	Alerts the collections team when a customer misses a payment and escalates according to the collections policy timeline.

Capabilities satisfied¶

Capability	Title	Mode	How
CAP-097	Loan lifecycle state management	`AUTO`	Transitions loan accounts through the full state machine (current, arrears, hardship, default, written-off) and notifies downstream systems at each transition.
CAP-098	Arrears & collections logic	`ALERT`	Triggers the collections workflow when a payment is missed, escalating through configured steps (reminder, notice, referral) based on days past due.
CAP-099	Hardship & restructure handling	`AUTO`	Accepts hardship requests, applies the configured relief rules (payment pause, reduced amount, term extension), and journals the restructure to the loan account.

Part of SD05 — Credit Decisioning & Loan Platform Compiled 2026-05-22 from source/entities/modules/MOD-065.yaml