Employee loans & advances

Employee creates request
        ↓
      DRAFT  ← employee can edit / withdraw
        ↓ submit
  PENDING_HR     OR     PENDING_MANAGER  (per-tenant setting)
        ↓                        ↓ manager approves
        ↓                  PENDING_HR
        ↓                        ↓
        ←—————————————— HR reviews → may EDIT amount / tenure / interest
        ↓
   APPROVED → creates active EmployeeLoan → first EMI in next payroll
   OR
   REJECTED with reason → employee notified by email

The optional manager step is controlled by Company.loanRequiresManagerApproval. Default: off (requests go straight to HR). Toggle on the Company settings page.

1. Open /me/loans.
2. Click Apply for advance.
3. Enter amount in ₹, tenure (1–60 months), and a brief purpose (medical, education, etc.).
4. Click Submit for approval. The request appears in your queue with status PENDING_HR (or PENDING_MANAGER if your company requires manager pre-approval).
5. You'll receive in-app + email notifications at each state change.
6. You can withdraw the request any time before HR approves.

1. Open /admin/loans.
2. "Pending approval" section shows all requests awaiting your decision.
3. Click Review to open the dialog.
4. You can edit the amount, tenure, and interest rate before approving — the employee's request stays unchanged for audit; your edits become the loan's actuals.
5. Click Approve to create the active loan. EMI will be auto-deducted from the next payroll run.
6. Click Reject to record a reason — the employee sees it on their dashboard and via email.

• When you generate a payroll for a given month/year, each active loan's EMI is computed for that period.
• EMI = principal / tenure (0% interest), or the standard amortization formula for non-zero rates.
• The EMI lands in otherDeductions on the employee's payslip — visible in the breakdown table.
• Each deduction creates an EmployeeLoanInstallment row linking the loan to the payslip, with the outstanding balance before/after.
• When outstanding reaches 0, the loan auto-transitions to COMPLETED.
• Idempotent: re-running payroll for the same period does not double-deduct. If an installment already exists for (loan, period), the second run skips it.

• Early closure — HR clicks "Close early" on the active loan, enters lump-sum amount. Status → CLOSED_EARLY, outstanding zeroed.
• Pause / resume — useful when employee is on unpaid leave. EMI skipped for paused months, tenure effectively extends.
• Waive — HR forgives the remaining balance. Status → WAIVED, outstanding zeroed, audit log preserves who waived and why.
• Offboarding — when an employee exits, outstanding balance is surfaced in the FNF preview (under "recoveries") and deducted from their full-and-final settlement.
• Termination mid-tenure — if outstanding can't be fully recovered from FNF, HR can waive the residual.

Per Section 17(2)(viii) of the Income Tax Act, an interest-free or below-market-rate loan from employer is a taxable perquisite if the aggregate loan exceeds ₹20,000. The "perquisite value" is the difference between the SBI rate and the rate you charged.

We do not auto-compute this perquisite. Surface it on the employee's Form 16 by adding a manual line to their tax declarations if applicable. Consult your CA — exact treatment varies by use case.

Module key LOANS in /admin/modules. Currently priced at ₹2/employee/month, billed only on employees who have at least one active loan in the period. Disabled by default for new tenants.

• Every state transition (apply, submit, manager-decide, HR-approve/reject, close-early, waive, pause) is timestamped + actor-attributed
• HR edits to the amount/tenure/interest are stored separately from the employee's request — full audit trail on changes
• Employees can only see their own loans and requests
• Managers can only see their direct reports' loan requests (when manager approval is on)
• HR admins see the full company-wide queue