Loans

Payroll → Loans & Claims → Loans (/loans) — employee loans and advances with recovery schedules. Requires payroll:read to view, payroll:manage to create.

Loans — per-employee loans

Entry point

The page is per-employee. The employee selector is kept in the URL (?employee=) so returning from New Loan or Schedule lands on the same employee.

• Search — SearchInput debounced 300 ms via useDebounce → usePayrollEmployeeOptions(search) (employeeCode + firstName lastName).
• Employee (select) — employeeCode — firstName lastName; includes the currently selected employee even when it wouldn't appear in the debounced search (selectedEmployee fallback).
• employeeId empty → no table; employeeId set → useEmployeeLoans(employeeId).

Column	Meaning
Code	loanCode (mono)
Type	loanType (HOME_LOAN → HOME LOAN etc.)
Principal	principal (money)
Interest %	interestRate%
Tenure (mo)	tenureMonths
Monthly	monthlyInstallment
Recovered	recoveredAmount
Status	StatusBadge (ACTIVE / CLOSED / etc.)

Row action: Schedule (/loans/:loanId/schedule?employee=) — amortization table (LoanSchedulePage).

Creating a loan

New Loan (top right, payroll:manage) → /loans/new?employee= (LoanFormPage):

• Fields: employee (if not pre-selected), loan type, principal, interest rate, tenure, start month, deduction component (which component carries the recovery), remarks.
• Validation: principal > 0, tenure > 0, monthly ≤ net pay sanity check (warning, not block).
• Saving creates EmployeeLoan via POST /employee-loans; recovery rows are generated for the loan's tenure.

Recovery

Each pay run that includes the employee and whose period overlaps the loan's schedule will create a deduction line (monthlyInstallment split) until recoveredAmount == principal + interest. The Schedule page shows each installment: due date, amount, recovered vs pending, and which run paid it.

:::note Run integration Loans are not manually added as adjustments — the run's compute reads ACTIVE loans for employees in the run and injects the recovery deduction automatically. :::