Loan Booking

What This Page Does

The Loan Booking page (new-loan) is the primary form for creating new loan records in Sodlapp. A loan officer fills in four sequential sections — applicant details, loan parameters, repayment schedule, and applicable charges — before submitting the completed record to the backend.

All key financial figures (EMI, DSR, disburse amount, total charges) update in real time as fields are changed. Submission is blocked if the computed Debt-Service Ratio exceeds the system-wide limit configured in App Settings.

On successful submission, the user is redirected to loan-documents?loan_id=<id>&new=1 where they can download and print the loan agreement. If the new loan was a Top-Up that automatically closed an existing disbursed loan, a toast notification confirms the closed serial number.

Page Structure

The form is split into four visually distinct sections, each rendered as a white card with a colour-coded 3px top stripe and a matching section icon.

API Endpoints Consumed

Seven PHP API files are consumed by this page. All return {"success": true/false, "data": ...} JSON envelopes.

Application

A Customer Search

Typing into the search field triggers searchCustomers(q) after a 300 ms debounce. Results appear in an absolute-positioned dropdown; clicking an item calls selectCustomer(c).

B Core Loan Parameters

Loan Details

This section handles the Ministry cascade and loan classification fields.

A Cascading Location Dropdowns

B Classification & Outstanding

Repayment Schedule

Two dropdowns (month and year) define the first repayment date. The system defaults these to the next calendar month on page load. A readonly display field shows the computed date as a human-friendly label (e.g. "29 August 2025"). The 29th is used as the standard monthly deduction date.

A Schedule Preview

When both a loan amount and a repayment date are set, a preview panel appears beneath the date fields showing the computed EMI across key months: payments 1, 2, 3, and the final payment (with an opacity dim). If the tenor is 3 months or fewer, all months are shown. The preview regenerates on every change to fLoanAmount, fTenor, or either date dropdown.

// Indices shown: [0, 1, 2, tenor-1]  (unique, deduped)
const indices = tenor <= 3
  ? Array.from({length: tenor}, (_,i) => i)
  : [0, 1, 2, tenor - 1];

const uniqueIdx = [...new Set(indices)];

// Each item shows: EMI amount, calendar label
// Final item is visually dimmed (opacity: 0.7)

Charges

Charges are loaded from api/charges_api?type=list on page init. Each charge has a rate_type of either "rate" (percentage of loan amount) or "fixed" (fixed Naira amount). They are selected one at a time via a dropdown — the same charge cannot be added twice.

A Charge Calculation

const amt = fixed > 0
  ? fixed                   // fixed Naira amount
  : (pct / 100) * loan;   // % of loan principal

// Amounts recompute whenever loanAmount changes (in recalculate())
appCharges = appCharges.map(c => ({
  ...c,
  amount: c.fixed > 0 ? c.fixed : (c.pct / 100) * loan
}));

B Summary Cards

Two amount cards sit above the charges table and update in real time:

Financial Calculations

1 EMI Formula

The EMI uses a flat-rate model — interest is computed as a fixed monthly amount on the full original principal (not a declining balance), then added to the monthly principal repayment.

2 DSR Formula

3 Maintenance Fee

4 Disburse Amount

DSR Enforcement

The DSR limit is loaded from api/settings_api into appSettings.app_dsr. The system supports a percentage string (e.g. "33%") or a plain number — both are parsed identically. If no limit is configured, DSR is shown as information only and does not block submission.

Active Loan Detection

Immediately after a customer is selected, checkActiveLoan(customerId) runs in the background. It fetches all disbursed loans via api/loan_api?type=list&status=Disbursed&per_page=500 and looks for one matching the customer's ID.

// 1. Fetch all Disbursed loans
const activeLoan = loans.find(l =>
  String(l.customer_fk) === String(customerId)
  && l.loan_status === 'Disbursed'
);

// 2. If found, fetch full loan detail for balance
const outstanding = parseFloat(
  loan.balance ?? loan.outstanding ?? loan.loan_amount
) || 0;

// 3. Auto-fill Outstanding field + set Loan Type = Top-Up
// 4. Show the blue Active Loan Notice banner

The notice banner displays a mini-table with: original loan amount, total paid, outstanding balance, paid percentage, payment count, and last payment date. It is automatically hidden when the customer is cleared via the × button.

Submission Payload

On submit, a JSON payload is POSTed to api/loan_api. The full payload structure is below.

{
  "customer_id":           "42",
  "loan_amount":            500000,
  "tenor":                  12,
  "net_salary":             150000,
  "state":                  "3",
  "ministry":               "17",
  "sub_ministry":           "5",
  "loan_type":              "new",
  "sector":                 "state",
  "outstanding":            0,
  "loan_repayment_date":    "2025-09-01",
  "charges": [
    {
      "charge_id":    "2",
      "charge_name":  "Management Fee",
      "charge_pct":   2.5,
      "charge_fixed": 0,
      "charge_amt":   12500,
      "rate_type":    "rate"
    }
  ],
  "total_charges":          12500,
  "ministry_interest_pct":  18,
  "interest_fee":           90000,
  "disburse_amount":        487500,
  "emi":                    49166.67,
  "maintenance":            0,
  "dsr":                    "32.78"
}

A Payload Fields Reference

B Success Response

{
  "success": true,
  "data": {
    "loan_id":        187,
    "old_loan_closed": true,
    "closed_serial":   "LN-2025-0041"
  }
}

On success, the UI waits 1.2 seconds then redirects to loan-documents?loan_id={id}&new=1. If no loan_id is returned, it falls back to manage-loans.

JavaScript State Variables

Key Functions

Validation Rules

Client-side validation runs inside submitLoan() before the API call. Failed fields are highlighted with a red border (1.6 s auto-reset) via hl(id) and an error banner appears at the top of the page.