Servicing Operations¶

The apps.servicing module handles post-origination loan management: modifications, forbearance, deferments, promise-to-pay, payoff quotes, suspense accounts, payment plans, and service credits.

Loan Modifications¶

Modification Types¶

Type	Effect
`rate_change`	New interest rate; schedule recalculated
`term_extension`	Extended maturity date; reduced payments
`principal_forgiveness`	Balance reduced; forgiveness expense in GL
`capitalization`	Past-due interest/fees added to principal; re-amortized
`reage`	Reset delinquency status; re-age the loan

Approval Workflow¶

Modifications follow a three-step workflow:

pending → approved → applied
              └──→ rejected
                    └──→ failed

Create (pending) --- Propose new terms
Approve (approved) --- Authorized user approves the modification
Apply (applied) --- New terms take effect

Each step is a separate API call. The service layer validates transitions and enforces business rules.

Terms Snapshot¶

When a modification is applied, the service snapshots the loan's terms before and after:

{
  "terms_before": {
    "interest_rate": "0.085",
    "term_months": 36,
    "monthly_payment": "312.50"
  },
  "terms_after": {
    "interest_rate": "0.065",
    "term_months": 48,
    "monthly_payment": "245.00"
  }
}

Amortization Regeneration¶

Applying a modification automatically regenerates the amortization schedule with the new terms.

Principal Forgiveness and Form 1099-C¶

When principal forgiveness is $600 or more, a Form1099C record is automatically created for tax reporting purposes.

Capitalization¶

Capitalization rolls accrued interest and/or outstanding fees into the principal balance:

Calculates total accrued interest and/or outstanding fees
Adds the amount to the loan's principal
Posts GL entries (DR Interest/Fees Receivable, CR Loans Receivable adjustments)
Regenerates the amortization schedule with the new principal

Forbearance¶

Forbearance temporarily suspends or reduces payment requirements:

Types¶

Type	Description
Full forbearance	No payments required during the period
Partial forbearance	Reduced payment amount during the period

Configuration¶

Field	Description
`start_date` / `end_date`	Forbearance period
`reduced_payment`	Payment amount during partial forbearance
`interest_accrues`	Whether interest continues accruing
`post_forbearance_action`	What happens when forbearance ends

Post-Forbearance Actions¶

Action	Description
`capitalization`	Roll accrued interest into principal
`repayment_plan`	Structured catch-up plan
`modification`	Modify loan terms
`deferment`	Defer missed payments to end of loan
`resume_amortization`	Resume normal schedule

System Effects¶

Loan sub_status set to in_forbearance
Collections and dunning are suppressed
Daily Celery task auto-completes forbearance when the end date passes

Deferment¶

Deferment moves scheduled payments to the end of the loan term:

Field	Description
`periods_deferred`	Number of periods to defer
`deferred_amount`	Total amount being deferred
`interest_treatment`	How interest is handled (see below)

Interest Treatment Options¶

Treatment	Description
`accrues`	Interest accumulates; added to balance at deferment end
`capitalized`	Interest rolled into principal immediately
`foregiven`	No interest accrues during deferment (subsidized)

Deferment marks the corresponding amortization periods as is_deferred = True and extends the loan's maturity date.

Promise to Pay¶

Records a borrower's verbal or written commitment to pay:

Field	Description
`promised_amount`	Amount the borrower committed to pay
`promised_date`	Date by which payment should be received
`status`	`pending`, `fulfilled`, or `broken`

Tracking¶

Linked to the collection contact that produced it
A daily Celery task detects broken promises (promised date passed with no matching payment)
Broken promises re-queue the loan in collection workflows
Fulfillment rates tracked for collector performance reporting

Payoff Quotes¶

Payoff quotes calculate the total amount needed to close a loan:

Component	Description
`principal_balance`	Outstanding principal
`accrued_interest`	Interest accrued through the quote date
`outstanding_fees`	Unpaid assessed fees
`per_diem_interest`	Daily interest for days past the quote date
`prepayment_penalty`	Penalty amount (if applicable)
`total_payoff`	Sum of all components
`good_through_date`	Quote expiration date

Prepayment Penalty Methods¶

Method	Calculation
Percentage of balance	`balance × penalty_rate`
Months of interest	`monthly_interest × penalty_months`
Yield maintenance	Present value of remaining interest payments
Step-down	Declining penalty by year (e.g., 5%/4%/3%/2%/1%/0%)

The penalty method is configured per lending program.

Payoff Receipt¶

When a payoff payment is received:

Compared against the quote (adjusted for per-diem interest)
Exact or over-payment closes the loan
Over-payment excess held in suspense for refund
Under-payment held in suspense for manual resolution
Loan transitions to paid_off; collateral liens released

Suspense Accounts¶

Suspense holds unapplied funds:

Scenario	Source
Partial payment below minimum	Payment too small to allocate
Overpayment on payoff	Excess beyond payoff amount
Unidentified payment	Cannot match to a loan

Actions¶

Action	Description
Apply	Apply suspense funds to the loan balance
Refund	Return funds to the borrower

All suspense movements create GL entries: DR/CR Suspense ↔ Cash.

Payment Plans¶

Structured repayment plans for borrowers in difficulty:

Plan Type	Description
`catch_up`	Spread arrears over future payments
`deferment`	Defer arrears to end of loan
`forbearance_cure`	Plan to catch up after forbearance ends
`settlement`	Partial satisfaction of debt

Settlement plans include a settlement_pct field indicating what percentage of the outstanding balance satisfies the debt.

Service Credits¶

Account credits applied to a borrower's loan:

Credit Type	Use Case
`adjustment`	Balance correction
`settlement`	Settlement credit
`courtesy`	Goodwill credit
`compensation`	Error compensation