21. Provident Fund & Gratuity
Story
Every payroll run, a slice of each employee's pay quietly moves into their provident fund — a long-term savings pot the company pays into as well. Months later, when someone needs an advance or finally leaves, that balance has to be exactly right, to the cent. This chapter is about how Zetta keeps it that way without anyone babysitting a spreadsheet.
Happy Path
Each approved payroll run deducts the employee's PF contribution and records the employer's matching share, posting both to that employee's PF passbook as dated ledger entries. The payslip shows a clear Provident Fund line.
The employee opens their PF passbook from self-service and sees a running statement: their own contributions, the employer's vested share, any accrued interest, and any advances they've taken.
When an employee needs cash, they request a PF withdrawal. It lands in the admin withdrawal queue as PENDING. An admin reviews and approves it; the payout is recorded against the balance, to be recovered or drawn down per policy.
On separation, the final settlement folds the PF balance in automatically — employee contributions plus the employer's vested amount plus interest minus any advances recovered — alongside gratuity, a tenure-based lump sum the company owes longer-serving staff.
It's reverse-safe: if a run is voided or reprocessed, its PF contributions roll back with compensating ledger entries, so the passbook never double-counts and never drifts from the payslips.
Failure Modes
| Failure | What the user sees | What happens next |
|---|---|---|
| Employee has no PF configured | No Provident Fund line on the payslip | Set up the PF contribution under salary/statutory setup first |
| Withdrawal exceeds available balance | "Amount exceeds available balance" | Employee lowers the amount or waits for more to accrue |
| Withdrawal still awaiting review | Request sits as PENDING in the queue | An admin approves or rejects before any money moves |
| Run voided after PF posted | PF entries reversed with a compensating entry | Passbook returns to its prior balance, no residue |
| Duplicate withdrawal submit | Second request blocked | Idempotency prevents a double payout |
| Separation with an unrecovered advance | Advance netted off the settlement | Final PF payout = balance − outstanding advance |
Edge Cases
| Scenario | Behavior | Why |
|---|---|---|
| Employer share not fully vested | Only the vested portion is paid on exit | The vesting schedule guards against early-leaver windfalls |
| Reprocessing a payroll run | PF amounts are restored, then recomputed | Never double-counts a contribution |
| Employee below the gratuity service minimum | No gratuity; PF is still paid out in full | Gratuity requires a minimum qualifying tenure |
| Interest accrual at a period boundary | Interest posts per the configured period, not mid-cycle | Keeps statements clean and reconcilable |