Loan restructure and variation workflow¶


ID	`MOD-132`
System	SD05
Repo	`bank-credit`
Build status	Deployed
Deployed	Yes
Last commit	`e8630d06a564fa6ff7c99f4bae5a09dcfb63c04e`

Purpose¶

Manages the lifecycle of customer-initiated changes to the terms of an existing loan. A loan variation covers repayment frequency changes, switching between variable and fixed interest rates, extending the loan term, restructuring repayments, and capitalising arrears. Loan variations are a routine commercial product feature — distinct from financial hardship assistance (MOD-139) — and must be governed by a structured workflow that ensures regulatory re-disclosure and credit re-assessment where the variation is material.

Regulatory context¶

CCCFA (NZ) s108 and NCCP (AU) require the bank to re-disclose revised contract terms whenever a loan variation materially changes the obligations of the borrower. Where a variation increases the credit exposure — such as extending the term or capitalising arrears — the responsible lending obligation under s9C CCCFA and s130 NCCP also requires the bank to assess whether the variation is unsuitable for the borrower given their current financial position. This creates two distinct regulatory gates: a disclosure gate (every variation) and a creditworthiness gate (material variations only).

Break cost disclosure under CCCFA and the bank's own consumer credit policies requires that any cost the customer will incur by breaking a fixed rate period is calculated and acknowledged before the variation is confirmed. This is a pre-condition, not a post-event notification.

Variation types¶

Variation type	Credit reassessment required	Break cost disclosure required	Notes
Term extension > 12 months	Yes	No	Increases total interest payable — material change
Term extension ≤ 12 months	No	No	Minor adjustment — disclosure only
Repayment frequency change	No	No	e.g. monthly to fortnightly — disclosure only
Rate type switch (variable → fixed)	No	No	No increase in exposure — disclosure only
Rate type switch (fixed → variable)	No	Yes	Break cost on fixed period exit
Early repayment (partial or full)	No	Yes	Break cost on fixed period exit
Capitalisation of arrears	Yes	No	Increases principal — material change
Repayment restructure	Yes	No	Extends effective term or reduces repayment amount

Assessment rules¶

The system determines materiality by comparing the variation type against the configured materiality rules at the time of request. The two assessment paths are:

Creditworthiness gate path. Term extensions > 12 months, rate type switches that increase the balance or term, capitalisation of arrears, and repayment restructures that reduce the scheduled repayment amount invoke MOD-029. The variation is held in assessed status pending the outcome. A declined assessment rejects the variation and notifies the customer with the reason.

Disclosure-only path. Repayment frequency changes, minor term adjustments (≤ 12 months), and variable-to-fixed rate switches proceed directly to disclosure without a credit check. The revised schedule and terms are calculated, the disclosure is dispatched via MOD-050, and the variation is confirmed on acknowledgement.

Break cost gate. Independent of the above two paths, any variation involving exit from a fixed rate period invokes MOD-163 to calculate the break cost. The variation is held in disclosed status until the customer acknowledges the break cost figure via MOD-050. The acknowledgement reference is written to the variation record before the variation moves to confirmed.

Data model¶

-- credit.loan_variations
CREATE TABLE credit.loan_variations (
  variation_id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  loan_account_id       UUID NOT NULL REFERENCES credit.loan_accounts(id),
  variation_type        TEXT NOT NULL CHECK (variation_type IN (
                          'term_extension', 'frequency_change', 'rate_type_switch',
                          'repayment_restructure', 'capitalisation_of_arrears',
                          'early_repayment'
                        )),
  previous_terms        JSONB NOT NULL,
  proposed_terms        JSONB NOT NULL,
  status                TEXT NOT NULL DEFAULT 'requested' CHECK (status IN (
                          'requested', 'assessing', 'assessed', 'disclosed', 'confirmed', 'rejected', 'expired'
                        )),
  assessment_required   BOOL NOT NULL DEFAULT false,
  credit_check_id       UUID,            -- reference to MOD-029 assessment record
  disclosure_id         UUID,            -- reference to MOD-050 disclosure record
  break_cost_acknowledged BOOL NOT NULL DEFAULT false,
  acknowledgement_ref   TEXT,            -- break cost acknowledgement reference from MOD-050
  requested_by          UUID NOT NULL,   -- customer_id or agent_id
  rejection_reason      TEXT,
  created_at            TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at            TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX ON credit.loan_variations (loan_id);
CREATE INDEX ON credit.loan_variations (status);

previous_terms and proposed_terms capture the full term snapshot — interest rate, repayment amount, repayment frequency, term end date, rate type, and any other material fields — so the before/after state is preserved without relying on the current loan record at time of audit.

Key operations¶

Request. Customer or agent submits a variation request specifying the variation type and proposed terms. The system creates a credit.loan_variations record with status requested and emits bank.credit.loan_variation_requested. The materiality rule engine evaluates the variation type and sets assessment_required.

Assessment gate. If assessment_required is true, MOD-029 is invoked with the customer's current financial profile and the proposed terms. The outcome is written to credit_check_id. An approved assessment moves status to assessed; a declined assessment moves status to rejected and closes the variation.

Break cost calculation. If the variation type requires break cost disclosure, MOD-163 calculates the cost and MOD-050 dispatches the disclosure. The variation is held in disclosed status. On acknowledgement by the customer, break_cost_acknowledged is set to true, acknowledgement_ref is populated, and status advances.

Disclosure dispatch. MOD-050 generates the revised disclosure document including the new repayment schedule from MOD-112, the new rate, the new term end date, and the total interest payable comparison. The disclosure_id is written to the variation record. The variation is held at disclosed until the customer confirms.

Confirmation. On customer confirmation, status moves to confirmed. MOD-112 regenerates the amortisation schedule and applies it to the loan. MOD-063 and MOD-050 deliver the updated schedule to the customer within 24 hours. The event bank.credit.loan_variation_confirmed is emitted.

Rejection. The variation can be rejected at any stage — by the credit engine, by the customer declining the disclosure, or by an agent. The rejection reason is recorded and status is set to rejected. All events up to that point remain in the log.

Requirements¶

ID	Requirement
FR-589	System shall determine whether a requested loan variation requires credit reassessment by comparing the variation type against the configured materiality rules; material variations (term extension > 12 months, rate type switch, capitalisation of arrears) must invoke MOD-029 before proceeding; non-material variations (repayment frequency change, minor term adjustment) must proceed to disclosure without reassessment.
FR-590	System shall generate an updated amortisation schedule via MOD-112 for every confirmed loan variation and deliver it to the customer via MOD-063 and MOD-050 within 24 hours of the variation being confirmed, showing the revised repayment amount, new term end date, and any change in total interest payable.
FR-591	System shall enforce the break cost disclosure gate for any variation that involves early repayment or conversion of a fixed rate period — the variation must not be confirmed until the customer has acknowledged the break cost calculated by MOD-163 via MOD-050; the acknowledgement reference must be recorded on the variation record.
FR-592	System shall log every loan variation event — request, assessment decision, disclosure dispatch, customer confirmation, and any rejection — as an immutable record in `credit.loan_variations` with the requesting party, timestamp, and full before/after terms; the log must be available for regulatory examination without reconstruction.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-029	Pre-approval engine	Required	—	Credit decision engine re-assesses affordability for material variations before the variation can be confirmed.
MOD-112	Amortisation schedule engine	Required	—	Amortisation schedule is regenerated after any variation that changes the repayment amount or loan term.
MOD-050	Disclosure enforcement module	Required	—	Revised terms and break cost disclosure is delivered via disclosure management before the variation is confirmed.
MOD-053	Case & complaint management module	Optional	—	Agent-initiated case escalation for complex variations; escalate-to-case endpoint files a MOD-053 case and writes case_id to the variation record. Optional — no auto-escalation in v1.
MOD-063	Notification orchestration	Required	—	Customer notifications for variation receipt, assessment outcome, and confirmation/rejection are driven by bank.credit.loan_variation_* events consumed by MOD-063 — no direct call from this module.
MOD-163	Break-cost calculator	Required	—	Break-cost calculations for fixed-rate variations are performed by the general break-cost calculator — MOD-132 holds the `break_cost_calculation_id` reference on the variation record.
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.
MOD-104	AWS shared infrastructure bootstrap	Required	—	AWS shared infrastructure provisioned by MOD-104 (EventBridge buses, S3, KMS) is required before this module can be deployed.

Required by¶

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

Policies satisfied¶

Policy	Title	Mode	How
CRE-001	Credit Risk Management Policy	`GATE`	Material variations — term extension, rate type change, and capitalisation of arrears — require a fresh creditworthiness check via MOD-029 before the variation can proceed.
CON-004	Product Disclosure & Sales Practice Policy	`AUTO`	An updated disclosure showing the revised repayment schedule, new rate, and any break cost is automatically issued to the customer via MOD-050 before the variation is confirmed.
CON-005	Fee & Pricing Transparency Policy	`GATE`	Break cost disclosure must be acknowledged by the customer before any fixed-to-variable conversion or early repayment variation is processed — the variation is held until acknowledgement is recorded.
REP-004	Financial Statements Policy	`LOG`	Every loan variation event — request, assessment decision, disclosure dispatch, customer confirmation, and rejection — is logged as an immutable record for regulatory examination and responsible lending audit.

Capabilities satisfied¶

(No capabilities mapped)

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