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.
Gratuity has a second life before anyone leaves. Finance needs to carry it on the books as a provision, which means answering a question no payroll run asks: if everyone still accruing walked out today, what would we owe? The Gratuity Liability statement answers exactly that, for any date you name. Pick a valuation date, optionally narrow to a department, and you get every accruing employee with their months of service, the basis salary the policy resolves for them, and the amount accrued — plus a total to hand to the accountant, and a CSV or Excel export that carries the date and the assumptions inside the file.
The date is the whole point of the page. Basis salary is the structure in force on that date rather than today's, and the gratuity policy version active then is applied across the whole service period. So a statement dated the last day of the financial year is genuinely a year-end valuation, not this morning's numbers wearing an old label — and because the date lives in the URL, the link you send opens on your valuation rather than the reader's.
Two things on that statement look like errors and are not. Employees below the policy's minimum service appear with a zero and a Not yet eligible badge instead of being dropped, so the list is the whole workforce and you can see who is about to qualify. An amount that has stopped growing carries a Capped badge, meaning it reached the policy's maximum months of basis salary. Hiding either would make the population impossible to audit.
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 |
| Employee opens Gratuity Liability | "No gratuity liability to show" | The company-wide roll-up is manager-only; their own accrual is on their profile |
| No gratuity policy in force on the valuation date | Statement comes back empty | Set one up under Benefits Settings → Gratuity, then re-run the date |
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 |
| Gratuity policy changed mid-service | The version active on the valuation date is applied to the whole service period | Accrual is a valuation, not period-accurate accounting — the assumption is printed on the statement rather than hidden |
| Terminated employee on a past valuation date | Excluded from the liability statement | Their gratuity is already settled and recorded on the separation, so counting it again would double the provision |