K
Klivvr Blog

Loan Lifecycle Management: From Application to Payoff

An end-to-end guide to managing the full lifecycle of a loan within a lending platform, covering disbursement, repayment scheduling, collections, modifications, and payoff processing in TypeScript.

technical9 min readBy Klivvr Engineering
Share:

A loan does not end when it is approved. The post-origination lifecycle---disbursement, repayment, delinquency management, modifications, and eventual payoff---is where the bulk of operational complexity resides. A lending platform must track the precise state of every loan at every point in time, process payments accurately, handle exceptions gracefully, and provide both borrowers and internal teams with a clear picture of account status.

This article walks through the major phases of loan lifecycle management and demonstrates how to model them in TypeScript within a lending platform.

Loan Account Data Model

Once a loan is approved and funded, the application record gives way to a loan account record that tracks the ongoing financial state of the loan.

interface LoanAccount {
  id: string;
  applicationId: string;
  borrowerId: string;
  productType: string;
  status: LoanStatus;
  principal: number;
  interestRate: number;
  termMonths: number;
  disbursementDate: Date;
  maturityDate: Date;
  monthlyPayment: number;
  outstandingPrincipal: number;
  accruedInterest: number;
  totalPaid: number;
  nextPaymentDueDate: Date;
  daysPastDue: number;
  createdAt: Date;
  updatedAt: Date;
}
 
type LoanStatus =
  | "active"
  | "current"
  | "delinquent"
  | "default"
  | "in_modification"
  | "paid_off"
  | "charged_off"
  | "in_bankruptcy";
 
interface PaymentScheduleEntry {
  sequenceNumber: number;
  dueDate: Date;
  principalAmount: number;
  interestAmount: number;
  totalAmount: number;
  status: "scheduled" | "paid" | "partial" | "missed" | "waived";
  paidDate?: Date;
  paidAmount?: number;
}

The LoanAccount interface carries both the static terms of the loan (rate, term, original principal) and the dynamic state (outstanding principal, accrued interest, days past due). Keeping both on the same record simplifies most queries and reporting use cases.

Amortization and Payment Schedule Generation

When a loan is funded, the platform generates an amortization schedule that breaks down each monthly payment into principal and interest components.

class AmortizationCalculator {
  generateSchedule(
    principal: number,
    annualRate: number,
    termMonths: number,
    startDate: Date
  ): PaymentScheduleEntry[] {
    const monthlyRate = annualRate / 12;
    const monthlyPayment = this.calculateMonthlyPayment(
      principal,
      monthlyRate,
      termMonths
    );
 
    const schedule: PaymentScheduleEntry[] = [];
    let remainingPrincipal = principal;
 
    for (let i = 1; i <= termMonths; i++) {
      const interestAmount = Math.round(remainingPrincipal * monthlyRate * 100) / 100;
      const principalAmount = Math.round((monthlyPayment - interestAmount) * 100) / 100;
 
      // Adjust last payment for rounding
      const adjustedPrincipal =
        i === termMonths
          ? Math.round(remainingPrincipal * 100) / 100
          : principalAmount;
 
      const adjustedTotal =
        i === termMonths
          ? adjustedPrincipal + interestAmount
          : monthlyPayment;
 
      const dueDate = new Date(startDate);
      dueDate.setMonth(dueDate.getMonth() + i);
 
      schedule.push({
        sequenceNumber: i,
        dueDate,
        principalAmount: adjustedPrincipal,
        interestAmount,
        totalAmount: Math.round(adjustedTotal * 100) / 100,
        status: "scheduled",
      });
 
      remainingPrincipal -= adjustedPrincipal;
    }
 
    return schedule;
  }
 
  private calculateMonthlyPayment(
    principal: number,
    monthlyRate: number,
    termMonths: number
  ): number {
    if (monthlyRate === 0) return principal / termMonths;
 
    const factor = Math.pow(1 + monthlyRate, termMonths);
    const payment = (principal * monthlyRate * factor) / (factor - 1);
    return Math.round(payment * 100) / 100;
  }
}

A practical tip: always round monetary values to two decimal places at each step of the calculation, and adjust the final payment to absorb any rounding drift. This prevents the common problem where the sum of all scheduled payments does not exactly equal the principal plus total interest.

Payment Processing

Payment processing is the most transaction-sensitive part of the lifecycle. Each payment must be applied correctly---typically to fees first, then accrued interest, then principal---and the loan's state must be updated atomically.

interface Payment {
  id: string;
  loanAccountId: string;
  amount: number;
  type: "regular" | "extra_principal" | "payoff" | "late_fee";
  source: "ach" | "wire" | "card" | "internal";
  status: "pending" | "posted" | "failed" | "reversed";
  effectiveDate: Date;
  processedAt?: Date;
  allocation?: PaymentAllocation;
}
 
interface PaymentAllocation {
  feesApplied: number;
  interestApplied: number;
  principalApplied: number;
  overpayment: number;
}
 
class PaymentProcessor {
  constructor(
    private readonly loanRepo: LoanAccountRepository,
    private readonly scheduleRepo: PaymentScheduleRepository,
    private readonly ledger: LedgerService
  ) {}
 
  async processPayment(payment: Payment): Promise<PaymentAllocation> {
    const loan = await this.loanRepo.findById(payment.loanAccountId);
    if (!loan) throw new Error("Loan account not found");
 
    let remaining = payment.amount;
    const allocation: PaymentAllocation = {
      feesApplied: 0,
      interestApplied: 0,
      principalApplied: 0,
      overpayment: 0,
    };
 
    // 1. Apply to outstanding fees
    const outstandingFees = await this.ledger.getOutstandingFees(loan.id);
    if (outstandingFees > 0 && remaining > 0) {
      const feePayment = Math.min(remaining, outstandingFees);
      allocation.feesApplied = feePayment;
      remaining -= feePayment;
    }
 
    // 2. Apply to accrued interest
    if (loan.accruedInterest > 0 && remaining > 0) {
      const interestPayment = Math.min(remaining, loan.accruedInterest);
      allocation.interestApplied = interestPayment;
      remaining -= interestPayment;
      loan.accruedInterest -= interestPayment;
    }
 
    // 3. Apply to principal
    if (remaining > 0) {
      const principalPayment = Math.min(remaining, loan.outstandingPrincipal);
      allocation.principalApplied = principalPayment;
      remaining -= principalPayment;
      loan.outstandingPrincipal -= principalPayment;
    }
 
    // 4. Any overpayment
    if (remaining > 0) {
      allocation.overpayment = remaining;
    }
 
    // Update loan account
    loan.totalPaid += payment.amount - allocation.overpayment;
    loan.updatedAt = new Date();
 
    if (loan.outstandingPrincipal <= 0) {
      loan.status = "paid_off";
      loan.outstandingPrincipal = 0;
    } else if (loan.daysPastDue > 0) {
      await this.recalculateDelinquency(loan);
    }
 
    // Update schedule entries
    await this.markScheduleEntryPaid(loan.id, payment.effectiveDate, payment.amount);
 
    // Persist atomically
    await this.loanRepo.save(loan);
 
    payment.allocation = allocation;
    payment.status = "posted";
    payment.processedAt = new Date();
 
    return allocation;
  }
 
  private async recalculateDelinquency(loan: LoanAccount): Promise<void> {
    const schedule = await this.scheduleRepo.findByLoanId(loan.id);
    const now = new Date();
    const missedPayments = schedule.filter(
      (entry) => entry.status === "missed" && entry.dueDate < now
    );
 
    if (missedPayments.length === 0) {
      loan.daysPastDue = 0;
      loan.status = "current";
    } else {
      const oldestMissed = missedPayments.sort(
        (a, b) => a.dueDate.getTime() - b.dueDate.getTime()
      )[0];
      loan.daysPastDue = Math.floor(
        (now.getTime() - oldestMissed.dueDate.getTime()) / (1000 * 60 * 60 * 24)
      );
      loan.status = loan.daysPastDue > 90 ? "default" : "delinquent";
    }
  }
 
  private async markScheduleEntryPaid(
    loanId: string,
    effectiveDate: Date,
    amount: number
  ): Promise<void> {
    const schedule = await this.scheduleRepo.findByLoanId(loanId);
    const dueEntry = schedule.find(
      (entry) => entry.status === "scheduled" || entry.status === "missed"
    );
 
    if (dueEntry) {
      dueEntry.status = amount >= dueEntry.totalAmount ? "paid" : "partial";
      dueEntry.paidDate = effectiveDate;
      dueEntry.paidAmount = amount;
      await this.scheduleRepo.save(dueEntry);
    }
  }
}

The waterfall allocation order (fees, interest, principal) is standard across most lending products but can vary. Some products apply excess payments to future interest reduction, while others apply them entirely to principal. Making the allocation strategy configurable is a wise investment.

Delinquency Management and Collections

When borrowers miss payments, the platform must track delinquency status and initiate appropriate collections activities based on the severity.

interface CollectionsAction {
  id: string;
  loanAccountId: string;
  actionType: CollectionsActionType;
  scheduledDate: Date;
  executedDate?: Date;
  status: "scheduled" | "executed" | "skipped" | "failed";
  notes?: string;
}
 
type CollectionsActionType =
  | "payment_reminder"
  | "late_notice"
  | "phone_call"
  | "demand_letter"
  | "collections_agency_referral"
  | "charge_off";
 
class CollectionsEngine {
  private readonly escalationPolicy: EscalationStep[] = [
    { daysPastDue: 1, action: "payment_reminder" },
    { daysPastDue: 15, action: "late_notice" },
    { daysPastDue: 30, action: "phone_call" },
    { daysPastDue: 60, action: "demand_letter" },
    { daysPastDue: 90, action: "collections_agency_referral" },
    { daysPastDue: 180, action: "charge_off" },
  ];
 
  determineActions(loan: LoanAccount): CollectionsActionType[] {
    return this.escalationPolicy
      .filter((step) => loan.daysPastDue >= step.daysPastDue)
      .map((step) => step.action);
  }
 
  async runDailyCollectionsBatch(
    loans: LoanAccount[]
  ): Promise<CollectionsAction[]> {
    const actions: CollectionsAction[] = [];
 
    for (const loan of loans) {
      if (loan.status !== "delinquent" && loan.status !== "default") continue;
 
      const requiredActions = this.determineActions(loan);
      const existingActions = await this.getExecutedActions(loan.id);
      const executedTypes = new Set(existingActions.map((a) => a.actionType));
 
      for (const actionType of requiredActions) {
        if (!executedTypes.has(actionType)) {
          actions.push({
            id: crypto.randomUUID(),
            loanAccountId: loan.id,
            actionType,
            scheduledDate: new Date(),
            status: "scheduled",
          });
        }
      }
    }
 
    return actions;
  }
 
  private async getExecutedActions(loanId: string): Promise<CollectionsAction[]> {
    // Retrieve from repository
    return [];
  }
}
 
interface EscalationStep {
  daysPastDue: number;
  action: CollectionsActionType;
}

A practical tip: run the collections batch as a daily scheduled job, not in real time. This prevents duplicate actions and allows the operations team to review and potentially modify the batch before execution.

Loan Modifications and Restructuring

Borrowers sometimes face financial hardship and need their loan terms adjusted. Common modifications include term extensions, rate reductions, payment deferrals, and principal forbearance.

interface LoanModification {
  id: string;
  loanAccountId: string;
  modificationType: ModificationType;
  originalTerms: ModificationTerms;
  modifiedTerms: ModificationTerms;
  reason: string;
  requestedBy: string;
  approvedBy?: string;
  status: "requested" | "approved" | "applied" | "denied";
  effectiveDate?: Date;
  createdAt: Date;
}
 
type ModificationType =
  | "term_extension"
  | "rate_reduction"
  | "payment_deferral"
  | "principal_forbearance"
  | "combination";
 
interface ModificationTerms {
  interestRate: number;
  remainingTermMonths: number;
  monthlyPayment: number;
  deferredPayments?: number;
  forbearanceAmount?: number;
}
 
class LoanModificationService {
  constructor(
    private readonly loanRepo: LoanAccountRepository,
    private readonly scheduleRepo: PaymentScheduleRepository,
    private readonly amortization: AmortizationCalculator
  ) {}
 
  async applyModification(modification: LoanModification): Promise<LoanAccount> {
    if (modification.status !== "approved") {
      throw new Error("Modification must be approved before applying");
    }
 
    const loan = await this.loanRepo.findById(modification.loanAccountId);
    if (!loan) throw new Error("Loan account not found");
 
    // Update loan terms
    loan.interestRate = modification.modifiedTerms.interestRate;
    loan.termMonths = modification.modifiedTerms.remainingTermMonths;
    loan.monthlyPayment = modification.modifiedTerms.monthlyPayment;
    loan.status = "active";
    loan.updatedAt = new Date();
 
    // Regenerate amortization schedule from current point
    const newSchedule = this.amortization.generateSchedule(
      loan.outstandingPrincipal,
      modification.modifiedTerms.interestRate,
      modification.modifiedTerms.remainingTermMonths,
      modification.effectiveDate ?? new Date()
    );
 
    // Cancel remaining scheduled entries and replace
    await this.scheduleRepo.cancelFutureEntries(loan.id);
    await this.scheduleRepo.saveMany(
      newSchedule.map((entry) => ({ ...entry, loanAccountId: loan.id }))
    );
 
    await this.loanRepo.save(loan);
 
    modification.status = "applied";
 
    return loan;
  }
}

Payoff Processing

The final stage of the lifecycle is payoff, where the borrower satisfies all remaining obligations and the loan is closed.

interface PayoffQuote {
  loanAccountId: string;
  quoteDate: Date;
  goodThroughDate: Date;
  outstandingPrincipal: number;
  accruedInterest: number;
  outstandingFees: number;
  perDiemInterest: number;
  totalPayoffAmount: number;
}
 
class PayoffService {
  constructor(private readonly loanRepo: LoanAccountRepository) {}
 
  async generateQuote(loanId: string, asOfDate?: Date): Promise<PayoffQuote> {
    const loan = await this.loanRepo.findById(loanId);
    if (!loan) throw new Error("Loan account not found");
 
    const quoteDate = asOfDate ?? new Date();
    const dailyRate = loan.interestRate / 365;
    const perDiemInterest =
      Math.round(loan.outstandingPrincipal * dailyRate * 100) / 100;
 
    // Good through date is typically 10 business days out
    const goodThroughDate = new Date(quoteDate);
    goodThroughDate.setDate(goodThroughDate.getDate() + 14);
 
    const daysBetween = Math.ceil(
      (goodThroughDate.getTime() - quoteDate.getTime()) / (1000 * 60 * 60 * 24)
    );
 
    const totalInterest = loan.accruedInterest + perDiemInterest * daysBetween;
    const outstandingFees = 0; // Simplified; would query fee ledger
 
    return {
      loanAccountId: loanId,
      quoteDate,
      goodThroughDate,
      outstandingPrincipal: loan.outstandingPrincipal,
      accruedInterest: Math.round(totalInterest * 100) / 100,
      outstandingFees,
      perDiemInterest,
      totalPayoffAmount:
        Math.round(
          (loan.outstandingPrincipal + totalInterest + outstandingFees) * 100
        ) / 100,
    };
  }
}

A practical tip: payoff quotes should always include a per-diem interest figure and a "good through" date. Because interest accrues daily, the total payoff amount changes every day. Providing both values lets the borrower calculate the exact amount regardless of when within the window they send payment.

Conclusion

Loan lifecycle management is a complex domain that spans financial calculation, state management, external integrations, and regulatory requirements. The patterns presented here---amortization schedules generated with rounding-safe arithmetic, waterfall payment allocation, escalation-based collections, modification workflows with schedule regeneration, and payoff quotes with per-diem precision---form the operational core of any lending platform.

TypeScript's strong typing helps prevent the subtle monetary calculation errors and state transition bugs that can have real financial consequences. By modeling each phase of the lifecycle explicitly and maintaining comprehensive audit trails, a lending platform can provide both the automation needed for scale and the transparency required for compliance.

Related Articles

technical

Designing APIs for Lending Platforms

A comprehensive guide to designing robust, secure, and developer-friendly APIs for lending platforms, covering RESTful resource modeling, webhook architectures, idempotency, versioning, and partner integration patterns in TypeScript.

12 min read
business

Risk Management in Lending: Architecture and Strategy

A strategic guide to building a comprehensive risk management framework for lending platforms, covering credit risk, portfolio management, stress testing, concentration limits, and loss forecasting.

11 min read
business

Digital Lending Trends: What's Next for Fintech

A business-focused analysis of the trends shaping digital lending, including embedded finance, alternative data, real-time decisioning, open banking, and the evolution of lending-as-a-service platforms.

9 min read