Loan Installment

Navigation Path

Loan → Loan Installment

URL

loan/loan-installment

Description

The Loan Installment page is used to view loan/advance installments that were created from the Loan / Advance Transaction page.
This page is read-only except for delete action and supports multiple search and filter options.

Search & Filter Section

Used to filter loan installment records.

Filters

Month – Select month to filter installments
Search – Search by employee code

Loan Installment List Table

Displays all loan installment records added from the Loan / Advance module.

Table Columns

S No
Employee Code
Employee Name
Installment No
Deduction Amount
Actions

Table Features

Column-wise filter for:
- Employee Code
- Employee Name
- Installment No
- Deduction Amount
Checkbox selection per row
Pagination support

Actions

Delete Installment

A Delete icon is available for each record.
On click, a confirmation alert is shown.
Once confirmed, the selected installment record is permanently deleted.

⚠️ Editing and adding installments are not allowed on this page.

Notes

Installments displayed here are generated from the Loan / Advance Transaction page.
Only view and delete operations are supported.
Month filter helps in reviewing deductions for a specific payroll period.

API Endpoints

The Loan Installment module interacts with the following API endpoints:

Base URL

export const LOANINSTALLMENT_URL = '/api/loanInstallment'

Endpoints

Endpoint	Method	Description	Parameters/Body
`\$\{LOANINSTALLMENT_URL\}`	GET	Get all loan installments with pagination	Query: `page`, `limit`
`\$\{LOANINSTALLMENT_URL\}/:installmentId`	GET	Get loan installment by ID	Path: `installmentId`
`\$\{LOANINSTALLMENT_URL\}`	POST	Create a new loan installment	Body: `data`
`\$\{LOANINSTALLMENT_URL\}/:installmentId`	PATCH	Update an existing loan installment	Path: `installmentId`, Body: `body`
`\$\{LOANINSTALLMENT_URL\}/delete/:installmentId`	PATCH	Delete a loan installment (soft delete)	Path: `installmentId`
`\$\{LOANINSTALLMENT_URL\}/search`	POST	Search loan installments with filters	Body: `data` (search criteria)

RTK Query Hooks

The following hooks are available for frontend integration:

useGetAllInstallmentsQuery
useGetInstallmentByIdQuery
useCreateInstallmentMutation
useUpdateInstallmentMutation
useDeleteInstallmentMutation
useSearchInstallmentMutation

Field Definitions, Usage, and Calculation Logic

Loan Installments represent the individual successful recoveries of debt from an employee's monthly salary. Unlike transitions, these records are primarily system-generated.

1. Field Definitions

Field Name	Technical Name	Category	Description
Loan Ref	`loanId`	Identity	Reference to the source parent loan in `LoanMaster`.
Installment No	`installmentNumber`	Period	The sequential number of this repayment (e.g., 5 of 12).
Deduction Amt	`deductionAmount`	Financial	The exact amount subtracted from the employee's net pay.
Balance After	`balanceAfterPayment`	Financial	Snapshot of the remaining debt after this installment.
Month / Year	`month` / `year`	Period	The payroll cycle in which this deduction occurred.
Audit Link	`attendanceId`	Audit	Reference to the `SalaryAttendanceDetails` for that month.
Status	`status`	Workflow	`PENDING`, `PROCESSED`, `FAILED`.

2. Field Usage & Business Rules

A. Automated Generation

Installments are not typically created manually. They are generated by the Salary Auto Process when a record matches an helper loan.
The attendanceId is crucial for auditing; it links the financial deduction to the actual days worked by the employee.

B. Read-Only Integrity

To protect the audit trail, these records are read-only in the UI.
Modifications to deduction amounts should be handled via the Loan / Advance Transaction page or by unprocessing and re-processing the salary.

C. Status Transition

PENDING: Created at the start of salary processing.
PROCESSED: Set once the salary record is finalized and locked.
FAILED: Indicates the recovery could not be completed (e.g., salary reached zero net pay before full recovery).

3. Calculation Logic

A. Balance Snapshot Logic

Unlike the parent loan's balanceAmount, which is a "Live" value, the balanceAfterPayment is a snapshot.
Formula: balanceAfterPayment = (Current Loan Balance at Start of Process) - deductionAmount.
This provides a historical audit of how the debt was reduced over time.

B. Summary Aggregation

The search endpoint calculates real-time summary statistics for the filtered list:

Total Recovery: Sum(deductionAmount) across the selected month/year.
Average Recovery: Avg(deductionAmount) per employee for the period.
This is performed using MongoDB aggregation pipelines ($group, $sum, $avg).

End of Technical Documentation

Loan/Advance Special Loan