DEV Community: TankhaPay

Designing a Geofenced Attendance System: Haversine, GPS Accuracy and Anti-Spoofing (with Python)

TankhaPay — Fri, 09 Oct 2026 11:17:02 +0000

"Only allow check-in at the office" sounds like one if statement. In production it becomes a pile of edge cases: imprecise fixes inside concrete buildings, L-shaped warehouses, field staff who never visit the office, and the occasional fake-GPS app.

This post designs the server-side validation for a geofenced attendance system, with runnable Python (standard library only) and pytest tests, small enough to port to any stack.

Requirements

A realistic attendance system needs to handle:

Check-in and check-out only inside an approved geofence (office, plant, client site).
Multiple sites per employee. People move between branches; a punch is valid if it lands in any fence assigned to them for that date.
Shifts. The fence check answers "where"; the shift engine answers "when". Keep them separate so outcomes stay explainable.
Field staff. Sales and service teams may punch at customer locations, so you need ad-hoc or route-based fences, and a "needs review" path instead of a hard reject.

Validation should return ACCEPTED, REVIEW or REJECTED plus machine-readable reasons. Binary accept/reject is what makes these systems feel hostile.

Geofence models: circles vs polygons

Circles are a centre point plus a radius. The check is a great-circle distance compared with the radius, and the standard formula is Haversine, which treats the Earth as a sphere. Circles are trivial to configure (drop a pin, pick a radius) and they're what the mobile OS geofencing APIs use: Android's geofencing guide defines a fence as latitude, longitude and radius forming a circular area.

Polygons are a list of vertices, checked with ray casting: cast a ray from the point and count edge crossings. An odd count means the point is inside. Use polygons when the site is long, thin or irregular: a rail yard, a campus, a construction site, or an office tower beside a busy road where a generous circle would include the café across the street.

Rule of thumb: default to circles; switch to polygons when a circle covering the site would also cover a lot that isn't the site.

GPS accuracy realities

Every fix comes with an uncertainty, and the platforms are explicit about what it means:

On Android, Location.getAccuracy() "returns the estimated horizontal accuracy radius in meters of this location at the 68th percentile confidence level", i.e. there is a 68% chance the true position is inside a circle of that radius around the reported point.
On iOS, CLLocation.horizontalAccuracy is "the radius of uncertainty for the location, measured in meters": the coordinate is the centre of the circle and this value is its radius. A negative value means the coordinate is invalid.

Two consequences follow. First, a reported point inside the fence doesn't mean the person is inside. Second, even a "good" accuracy value is only a 68% statement on Android, so no threshold makes a punch certain.

Indoors it gets worse. Android's geofencing guide recommends a minimum fence radius of 100–150 m, notes that Wi-Fi-based accuracy is usually 20–50 m, and says that without Wi-Fi (for example in rural areas) accuracy can degrade to several hundred metres or even kilometres. A 30 m fence around an office floor will produce a steady stream of false rejections.

The policy used below:

ACCEPT if the whole uncertainty circle fits inside the fence: distance + accuracy <= radius (generalised as margin - accuracy >= -tolerance, where margin is the signed distance to the boundary).
REVIEW if the circle overlaps the boundary, or the fix is coarser than a ceiling (say 100 m).
REJECT if the punch is outside even after giving it the full accuracy radius.

The tolerance_m knob lets HR choose between "strict" and "forgiving" per site, without code changes.

Anti-spoofing signals

No single check stops a determined spoofer, and none of the techniques below is foolproof. They're signals: combine them, score them, and send ambiguous cases to review.

Mock-location flags. Android exposes Location.isMock(). The docs also warn that users may have legitimate reasons to mock location, so apps "should generally reject mock locations only when it is essential to their use case." Attendance arguably is one of those cases, but make the choice a policy setting. On Apple platforms, CLLocation.sourceInformation exposes isSimulatedBySoftware. Remember that a client-side flag is only as trustworthy as the client that reports it.
Impossible travel. Compute the speed implied by two consecutive punches. Subtract both accuracy radii from the distance first so honest jitter never trips the check. A Delhi punch followed by a Mumbai punch 30 minutes later is not a commute.
Device binding. Tie each employee to one or a few registered devices, and flag punches from unknown devices for review. Platform attestation, such as Google's Play Integrity API or Apple's App Attest, can help your server check that requests come from a genuine copy of your app.
Optional selfie or face match. Raises the cost of buddy-punching, but adds biometric data with its own consent, accuracy and fairness obligations. Make it a policy choice with a fallback path.
Server-side validation. The client collects; the server decides. Never trust an inside_fence: true from the app.

The code

Everything lives in one module, geofence.py, using dataclasses and the standard library.

"""Geofenced attendance: distance, point-in-polygon, punch validation, impossible travel.

Pure standard library. Python 3.10+.
"""
from __future__ import annotations

import math
from dataclasses import dataclass, field
from datetime import datetime
from enum import Enum

EARTH_RADIUS_M = 6_371_000.0  # mean Earth radius; Haversine treats Earth as a sphere


@dataclass(frozen=True)
class GeoPoint:
    lat: float
    lon: float


def haversine_m(a: GeoPoint, b: GeoPoint) -> float:
    """Great-circle distance in metres between two WGS84 lat/lon points (spherical model)."""
    phi1, phi2 = math.radians(a.lat), math.radians(b.lat)
    dphi = math.radians(b.lat - a.lat)
    dlmb = math.radians(b.lon - a.lon)
    h = math.sin(dphi / 2) ** 2 + math.cos(phi1) * math.cos(phi2) * math.sin(dlmb / 2) ** 2
    return 2 * EARTH_RADIUS_M * math.asin(math.sqrt(min(1.0, h)))


def _to_local_xy(p: GeoPoint, origin: GeoPoint) -> tuple[float, float]:
    """Equirectangular projection to metres around `origin`. Fine for site-sized areas."""
    x = math.radians(p.lon - origin.lon) * math.cos(math.radians(origin.lat)) * EARTH_RADIUS_M
    y = math.radians(p.lat - origin.lat) * EARTH_RADIUS_M
    return x, y


def point_in_polygon(p: GeoPoint, vertices: list[GeoPoint]) -> bool:
    """Ray casting (even-odd rule). Vertices in order, polygon implicitly closed.

    Treats lon as x and lat as y; valid for small polygons that don't cross the antimeridian.
    """
    inside = False
    n = len(vertices)
    for i in range(n):
        a, b = vertices[i], vertices[(i + 1) % n]
        if (a.lat > p.lat) != (b.lat > p.lat):  # edge straddles the horizontal ray
            x_cross = a.lon + (p.lat - a.lat) * (b.lon - a.lon) / (b.lat - a.lat)
            if p.lon < x_cross:
                inside = not inside
    return inside


def distance_to_polygon_edge_m(p: GeoPoint, vertices: list[GeoPoint]) -> float:
    """Shortest distance in metres from p to the polygon boundary (local planar approximation)."""
    px, py = 0.0, 0.0
    pts = [_to_local_xy(v, p) for v in vertices]
    best = math.inf
    for i in range(len(pts)):
        (ax, ay), (bx, by) = pts[i], pts[(i + 1) % len(pts)]
        dx, dy = bx - ax, by - ay
        seg2 = dx * dx + dy * dy
        t = 0.0 if seg2 == 0 else max(0.0, min(1.0, ((px - ax) * dx + (py - ay) * dy) / seg2))
        best = min(best, math.hypot(ax + t * dx - px, ay + t * dy - py))
    return best


@dataclass(frozen=True)
class CircleFence:
    fence_id: str
    center: GeoPoint
    radius_m: float

    def margin_m(self, p: GeoPoint) -> float:
        """Signed distance to the boundary: positive = inside by that many metres."""
        return self.radius_m - haversine_m(self.center, p)


@dataclass(frozen=True)
class PolygonFence:
    fence_id: str
    vertices: tuple[GeoPoint, ...]

    def margin_m(self, p: GeoPoint) -> float:
        d = distance_to_polygon_edge_m(p, list(self.vertices))
        return d if point_in_polygon(p, list(self.vertices)) else -d


Fence = CircleFence | PolygonFence


class Status(str, Enum):
    ACCEPTED = "ACCEPTED"
    REVIEW = "REVIEW"
    REJECTED = "REJECTED"


@dataclass(frozen=True)
class Punch:
    employee_id: str
    device_id: str
    kind: str                 # "IN" or "OUT"
    location: GeoPoint
    accuracy_m: float         # horizontal accuracy radius reported by the OS
    device_time: datetime     # when the fix/punch happened on the device
    is_mock: bool = False     # Android Location.isMock(); iOS CLLocationSourceInformation.isSimulatedBySoftware


@dataclass(frozen=True)
class AccuracyPolicy:
    tolerance_m: float = 0.0        # extra slack added to the fence when deciding ACCEPT
    max_accuracy_m: float = 100.0   # fixes coarser than this are never auto-accepted
    reject_mock: bool = True
    max_speed_mps: float = 70.0     # ~250 km/h; tune for your workforce (flights need a manual path)


@dataclass
class Decision:
    status: Status
    fence_id: str | None = None
    margin_m: float | None = None
    reasons: list[str] = field(default_factory=list)

    def escalate(self, status: Status, reason: str) -> None:
        order = [Status.ACCEPTED, Status.REVIEW, Status.REJECTED]
        if order.index(status) > order.index(self.status):
            self.status = status
        self.reasons.append(reason)


def implied_speed_mps(prev: Punch, cur: Punch) -> float:
    """Speed implied by two punches, giving the user the benefit of both accuracy radii."""
    dist = max(0.0, haversine_m(prev.location, cur.location) - prev.accuracy_m - cur.accuracy_m)
    seconds = (cur.device_time - prev.device_time).total_seconds()
    if seconds <= 0:
        return math.inf if dist > 0 else 0.0
    return dist / seconds


def validate_punch(
    punch: Punch,
    fences: list[Fence],
    policy: AccuracyPolicy = AccuracyPolicy(),
    previous: Punch | None = None,
    bound_devices: set[str] | None = None,
) -> Decision:
    """Decide ACCEPTED / REVIEW / REJECTED for a single punch. Run this on the server."""
    if not fences:
        return Decision(Status.REJECTED, reasons=["no active geofence for this employee/date"])

    # Pick the fence where the punch sits deepest (largest margin).
    best = max(fences, key=lambda f: f.margin_m(punch.location))
    margin = best.margin_m(punch.location)
    d = Decision(Status.ACCEPTED, best.fence_id, round(margin, 1))

    # Core rule: the whole uncertainty circle must fit inside the fence (+ tolerance).
    if margin - punch.accuracy_m >= -policy.tolerance_m:
        d.reasons.append("accuracy circle inside fence")
    elif margin + punch.accuracy_m >= 0:
        d.escalate(Status.REVIEW, "accuracy circle overlaps fence boundary")
    else:
        d.escalate(Status.REJECTED, "outside fence even after allowing for accuracy")

    if punch.accuracy_m > policy.max_accuracy_m:
        d.escalate(Status.REVIEW, f"fix too coarse ({punch.accuracy_m:.0f} m)")
    if punch.is_mock:
        d.escalate(Status.REJECTED if policy.reject_mock else Status.REVIEW, "mock location flag set")
    if bound_devices is not None and punch.device_id not in bound_devices:
        d.escalate(Status.REVIEW, "unrecognised device")
    if previous is not None:
        v = implied_speed_mps(previous, punch)
        if v > policy.max_speed_mps:
            d.escalate(Status.REVIEW, f"impossible travel ({v:.0f} m/s since last punch)")
    return d

A few design notes:

Polygon margin uses a local equirectangular projection; fine at site scale, not for country-sized shapes or the antimeridian.
Severity only ratchets up. escalate() never downgrades, so a new check can't accidentally approve something.

Sanity-checking Haversine

Connaught Place to India Gate is a handy Delhi test case. Using approximate coordinates for the centre of the CP circle (28.6315, 77.2167) and the India Gate monument (28.6129, 77.2295), the demo prints:

Haversine CP -> India Gate: 2416.3 m
WGS84 geodesic (geographiclib): 2411.7 m  diff=4.6 m (0.190%)

The spherical model is within 5 m of the ellipsoidal answer over about 2.4 km, negligible next to GPS uncertainty. (Exact numbers depend on the points you pick.)

Running the validator

at office centre, 12 m fix   -> ACCEPTED fence=cp-office margin=150.0 m  ['accuracy circle inside fence']
near office edge, 40 m fix   -> REVIEW   fence=cp-office margin=16.6 m  ['accuracy circle overlaps fence boundary']
on site polygon, 8 m fix     -> ACCEPTED fence=site-a margin=122.3 m  ['accuracy circle inside fence']
2 km away                    -> REJECTED fence=cp-office margin=-1907.1 m  ['outside fence even after allowing for accuracy']
mock location                -> REJECTED fence=cp-office margin=150.0 m  ['accuracy circle inside fence', 'mock location flag set']
coarse 400 m fix             -> REVIEW   fence=cp-office margin=150.0 m  ['accuracy circle overlaps fence boundary', 'fix too coarse (400 m)']
new device                   -> REVIEW   fence=cp-office margin=150.0 m  ['accuracy circle inside fence', 'unrecognised device']
Delhi -> Mumbai in 30 min implies 639 m/s
impossible travel punch -> REJECTED ['outside fence even after allowing for accuracy', 'impossible travel (639 m/s since last punch)']

Note the "near office edge" case: the point is about 17 m inside the fence, but with a 40 m accuracy radius the true position could be outside, so it goes to review.

Tests

from datetime import datetime, timedelta, timezone

import pytest

from geofence import (AccuracyPolicy, CircleFence, GeoPoint, PolygonFence, Punch, Status,
                      haversine_m, implied_speed_mps, point_in_polygon, validate_punch)

T0 = datetime(2026, 10, 9, 9, 0, tzinfo=timezone.utc)
CP = GeoPoint(28.6315, 77.2167)
INDIA_GATE = GeoPoint(28.6129, 77.2295)
SQUARE = [GeoPoint(0, 0), GeoPoint(0, 1), GeoPoint(1, 1), GeoPoint(1, 0)]


def mk(p, acc=10, minutes=0, mock=False, device="d1"):
    return Punch("E1", device, "IN", p, acc, T0 + timedelta(minutes=minutes), mock)


def test_haversine_cp_to_india_gate():
    # Cross-checked against a WGS84 geodesic (geographiclib) in demo.py
    assert haversine_m(CP, INDIA_GATE) == pytest.approx(2416, abs=15)


def test_haversine_one_degree_latitude():
    assert haversine_m(GeoPoint(0, 0), GeoPoint(1, 0)) == pytest.approx(111_195, abs=1)


def test_haversine_zero_and_symmetric():
    assert haversine_m(CP, CP) == 0
    assert haversine_m(CP, INDIA_GATE) == pytest.approx(haversine_m(INDIA_GATE, CP))


@pytest.mark.parametrize("pt,expected", [
    (GeoPoint(0.5, 0.5), True), (GeoPoint(1.5, 0.5), False), (GeoPoint(0.5, -0.1), False)])
def test_point_in_polygon(pt, expected):
    assert point_in_polygon(pt, SQUARE) is expected


def test_concave_polygon_notch_is_outside():
    u_shape = [GeoPoint(0, 0), GeoPoint(0, 3), GeoPoint(3, 3), GeoPoint(3, 2),
               GeoPoint(1, 2), GeoPoint(1, 1), GeoPoint(3, 1), GeoPoint(3, 0)]
    assert point_in_polygon(GeoPoint(2, 1.5), u_shape) is False   # inside the notch
    assert point_in_polygon(GeoPoint(0.5, 1.5), u_shape) is True


def test_accuracy_policy_accept_review_reject():
    fence = [CircleFence("f", CP, 100)]
    north_80m = GeoPoint(CP.lat + 80 / 111_195, CP.lon)
    assert validate_punch(mk(CP, acc=20), fence).status is Status.ACCEPTED
    assert validate_punch(mk(north_80m, acc=30), fence).status is Status.REVIEW   # 80+30 > 100
    assert validate_punch(mk(north_80m, acc=30), fence,
                          AccuracyPolicy(tolerance_m=15)).status is Status.ACCEPTED
    assert validate_punch(mk(INDIA_GATE, acc=30), fence).status is Status.REJECTED


def test_polygon_fence_uses_edge_margin():
    site = PolygonFence("s", (GeoPoint(28.6140, 77.2280), GeoPoint(28.6140, 77.2310),
                              GeoPoint(28.6118, 77.2310), GeoPoint(28.6118, 77.2280)))
    assert validate_punch(mk(INDIA_GATE, acc=8), [site]).status is Status.ACCEPTED
    assert validate_punch(mk(INDIA_GATE, acc=500), [site]).status is Status.REVIEW


def test_mock_location_rejected_and_unknown_device_reviewed():
    fence = [CircleFence("f", CP, 100)]
    assert validate_punch(mk(CP, mock=True), fence).status is Status.REJECTED
    r = validate_punch(mk(CP, device="other"), fence, bound_devices={"d1"})
    assert r.status is Status.REVIEW and "unrecognised device" in r.reasons


def test_impossible_travel():
    mumbai = GeoPoint(19.0760, 72.8777)
    prev, cur = mk(CP), mk(mumbai, minutes=30)
    assert implied_speed_mps(prev, cur) > 600
    r = validate_punch(cur, [CircleFence("f", CP, 100)], previous=prev)
    assert any("impossible travel" in x for x in r.reasons)
    # A short walk across the site is fine.
    assert implied_speed_mps(mk(CP), mk(INDIA_GATE, minutes=30)) < 2

$ python -m pytest -q
...........                                                              [100%]
11 passed in 0.03s

The 111,195 m figure in the one-degree test is simply 2π × 6,371,000 / 360, the arc length of one degree on a sphere of the radius the code uses.

Privacy and consent

Location is personal data, and attendance is a context with an obvious power imbalance. Design for minimal collection:

Collect location only at punch time. You don't need continuous background tracking to validate a check-in. If you also offer live tracking for field staff, make it a separate, clearly explained, time-boxed feature.
Set retention. Keep the raw fix for audit, then purge or coarsen coordinates once the payroll and dispute window closes.
Be transparent. Show employees the fence, explain why a punch went to review, and make disputes easy.

If you operate in India, the Digital Personal Data Protection Act, 2023 applies. The DPDP Rules, 2025 were notified in November 2025 with phased commencement: some provisions took effect on publication, the Consent Manager rule after one year, and most of the operational obligations (notice, security safeguards, data principal rights and others) eighteen months after publication. Timelines have been publicly discussed for revision, so confirm current status with counsel. Other jurisdictions have their own regimes; the habits above are worth adopting everywhere.

Design tips from production

Store raw punches immutably. Write each punch to an append-only table: coordinates, accuracy, mock flag, device ID, device time and server receipt time. Store decisions and manual overrides as separate rows that reference it. Never edit the punch itself.
Make geofences effective-dated config. A fence has valid_from and valid_to. When a branch moves or a radius changes, add a new version. Re-validating last March's punch must use last March's fence.
Handle offline punches deliberately. Field staff lose signal. Let the app queue punches with the device timestamp, and reconcile on the server: compare device time with receipt time, run impossible-travel checks across the whole queued sequence, and flag large clock skew. Android notes that getTime() comes from a clock that can jump, while elapsed realtime is monotonic, so send both.
Keep an audit trail. Every override needs a who, when and why.
Tune with data. Log margins and accuracy values for a few weeks before tightening tolerances.

Build vs buy

Everything here is buildable, and a small version is the best way to learn the trade-offs. At scale you also need rosters, leave, payroll integration and device management. HRMS platforms such as TankhaPay combine geofencing with face recognition, mobile check-in and live location tracking, so it's worth weighing that against owning the pipeline yourself.

Whichever route you take, the core ideas stay the same: respect the accuracy radius, treat anti-spoofing as layered signals rather than a silver bullet, decide on the server, and keep an immutable record of what happened.

References

Android Developers, Location API reference (getAccuracy, isMock, getTime, getElapsedRealtimeNanos): https://developer.android.com/reference/android/location/Location
Android Developers, Create and monitor geofences: https://developer.android.com/develop/sensors-and-location/location/geofencing
Apple Developer, CLLocation.horizontalAccuracy: https://developer.apple.com/documentation/corelocation/cllocation/horizontalaccuracy
Apple Developer, CLLocation.sourceInformation: https://developer.apple.com/documentation/corelocation/cllocation/sourceinformation
Apple Developer, CLLocationSourceInformation.isSimulatedBySoftware: https://developer.apple.com/documentation/corelocation/cllocationsourceinformation/issimulatedbysoftware
Android Developers, Play Integrity API overview: https://developer.android.com/google/play/integrity/overview
Apple Developer, Establishing your app's integrity (App Attest): https://developer.apple.com/documentation/devicecheck/establishing-your-app-s-integrity
Movable Type Scripts, Calculate distance, bearing and more between latitude/longitude points (Haversine): https://www.movable-type.co.uk/scripts/latlong.html
Press Information Bureau, "Government notifies DPDP Rules to empower citizens and protect privacy" (14 Nov 2025): https://www.pib.gov.in/PressReleasePage.aspx?PRID=2190014
Text of the DPDP Rules, 2025, G.S.R. 846(E), including Rule 1 commencement (Gazette Tracker copy): https://gazettetracker.com/g/CG-DL-E-14112025-267650

Written by the team at TankhaPay, a global HRMS and AI recruitment platform.

How to Calculate PF, ESI and Professional Tax in a Payroll Engine (with Python Examples)

TankhaPay — Fri, 09 Oct 2026 10:01:34 +0000

If you build payroll for Indian employees, three statutory deductions show up on almost every payslip: the Employees' Provident Fund (EPF), Employees' State Insurance (ESI) and state Professional Tax (PT). Each looks like a one-line percentage, and each hides edge cases: a ceiling that changed mid-month, slab boundaries worded differently by state, and scheme-specific rounding.

This post covers the rules as of October 2026 and builds a small config-driven Python calculator, with tests that reproduce EPFO's own worked examples.

1. Start with "wages", not "gross"

The four Labour Codes came into force on 21 November 2025. The Code on Wages, 2019 defines "wages" in section 2(y), and the Code on Social Security, 2020 defines it in section 2(88). Wages include basic pay, dearness allowance and retaining allowance. They exclude items such as HRA, conveyance, overtime, commission and the employer's PF contribution.

The part that matters for engineers is a proviso, usually called the 50% rule. If the excluded payments exceed one-half of total remuneration, the amount above that half is added back into wages. For example, with a gross of â‚¹50,000 and basic plus DA of â‚¹20,000, the exclusions are â‚¹30,000. That is â‚¹5,000 more than half of the gross, so statutory wages become â‚¹25,000.

EPFO's FAQs on the new ceiling confirm that coverage is tested against section 2(88) wages, not gross salary or CTC. Your engine needs an include/exclude flag per pay component; the function below simplifies this by treating everything except basic, DA and retaining allowance as excluded.

2. EPF: rates, the new â‚¹25,000 ceiling and the September split

Rates.

The employee contributes 12% of PF wages.
The employer also contributes 12%. Of that, 8.33% goes to the pension scheme (EPS, A/c 10) and the balance, 3.67%, goes to EPF (A/c 1).
EPFO's FAQ illustrations also show two employer charges: EDLI at 0.5% (A/c 21) and administrative charges at 0.5% (A/c 2).
The FAQs set a minimum administrative charge of â‚¹500 per month per establishment with at least one contributing member (an establishment-level rule, not per employee).

The ceiling. Notification S.O. 5109(E), dated 17 September 2026, set the wage ceiling for Chapter III of the Code (EPF, EPS and EDLI) at â‚¹25,000 per month. It replaced â‚¹15,000, the figure in place since September 2014, and took effect on the date of publication, 17 September 2026. PIB has confirmed the change, and EPFO has said it will not be pushed back to 1 October. As a result, the maximum EPS contribution rises from â‚¹1,250 to â‚¹2,083 a month.

The ceiling caps more than EPS. Where wages exceed the ceiling, both the employee and employer contributions are generally limited to the ceiling. The exception is an employee who has been permitted to contribute on higher wages. EPS membership is open only to employees whose wages did not exceed the ceiling when they joined or on the date the new ceiling took effect.

September 2026 is a split month. According to EPFO's FAQs, September is reported in a single ECR, but contributions are worked out for two periods:

1â€“16 September: the â‚¹15,000 ceiling applies, with wages apportioned at 16/30.
17â€“30 September: the â‚¹25,000 ceiling applies, with wages apportioned at 14/30.

Take an existing member earning â‚¹20,000. The EPF wage for September is 15,000 Ã— 16/30 + 20,000 Ã— 14/30 = â‚¹17,333.33. Employees who were previously excluded join EPF, EPS and EDLI from 17 September. If the employee share could not be deducted in September, it may be recovered in the next payroll. Both shares still have to be remitted by 15 October.

Rounding. The EPF Scheme rounds each contribution to the nearest rupee: 50 paise or more goes up, and anything less is dropped. The employer's EPF share is calculated as the difference between the total employer share and the EPS amount. That is why â‚¹25,000 gives an EPS amount of â‚¹2,083 (from 2,082.50) and an EPF amount of â‚¹917. EPFO's September illustration shows amounts in paise, so the engine below follows the scheme text and rounds once, at the end.

3. ESI: 0.75% + 3.25%, tested per contribution period

Rates: The employee pays 0.75% and the employer pays 3.25%. These rates have applied since 1 July 2019.
Eligibility: The limit is â‚¹21,000 per month, or â‚¹25,000 for persons with disability. It was last revised from 1 January 2017. The September 2026 EPF notification covers Chapter III only, so do not copy the EPF change into your ESI config.
Contribution periods: There are two, 1 Aprilâ€“30 September and 1 Octoberâ€“31 March. S.O. 2351(E), dated 8 May 2026, provides that an employee whose wages go above the ceiling after a period has started stays covered for the rest of that period. In code, coverage should be decided at the start of the period, or on joining, and not recalculated every month.
Low-wage exemption: According to ESIC, employees with an average daily wage of up to â‚¹176 pay no employee share, but the employer still pays its share.
Rounding: Engines commonly round ESI amounts up to the next rupee, and the calculator below does the same. We couldn't find a current official text confirming this under the Code, so keep it configurable.

4. Professional Tax: slabs as data

PT is set by each state, so model it as data. Two examples follow.

Maharashtra (Schedule I, from 1 April 2023):

Monthly salary	Men	Women
Up to â‚¹7,500	Nil	Nil
â‚¹7,501â€“â‚¹10,000	â‚¹175/month	Nil
â‚¹10,001â€“â‚¹25,000	â‚¹200/month, â‚¹300 in February	Nil
Above â‚¹25,000	â‚¹200/month, â‚¹300 in February	â‚¹200/month, â‚¹300 in February

Karnataka (from 1 April 2025): if salary is â‚¹25,000 and above, PT is â‚¹200 a month and â‚¹300 in February, for â‚¹2,500 a year. Below â‚¹25,000 it is nil.

Pay attention to the wording. Maharashtra says "exceeds â‚¹10,000", so a salary of exactly â‚¹10,000 pays â‚¹175. Karnataka says "â‚¹25,000 and above", so a salary of exactly â‚¹25,000 pays â‚¹200. Explicit inclusive bounds turn that difference into data instead of an if statement. Confirm the wage base each state expects with your compliance team.

5. The calculator

The calculator below handles the cases discussed above:

Mid-month joiners: wages are pro-rated by paid days.
Split months: the month is cut at every rule change, and each segment is capped at ceiling Ã— segment_days / days_in_month. For a normal month with one segment, this is the full ceiling, so a joiner's earned wage is still capped at â‚¹25,000 rather than a pro-rated ceiling. For September 2026, it gives EPFO's 16/30 and 14/30 apportionment.
Arrears: the original wage month is recalculated under that month's rules, and the difference is taken.
Voluntary PF (VPF): this raises only the employee share. The employer has no obligation to match it.

# statutory.py
"""Rules-driven PF / ESI / PT calculator (illustrative, not compliance-certified)."""
from dataclasses import dataclass, field
from datetime import date, timedelta
from decimal import Decimal as D, ROUND_HALF_UP, ROUND_CEILING
import calendar

def to_rupee(x: D) -> D:          # EPF: >= 50 paise up, < 50 paise dropped
    return x.quantize(D("1"), rounding=ROUND_HALF_UP)

def up_to_rupee(x: D) -> D:       # ESI: common practice, round up (verify!)
    return x.quantize(D("1"), rounding=ROUND_CEILING)

# ---------------- rules as data, effective-dated ----------------
@dataclass(frozen=True)
class EpfRule:
    effective_from: date
    wage_ceiling: D
    ee_rate: D = D("0.12")
    eps_rate: D = D("0.0833")
    edli_rate: D = D("0.005")
    admin_rate: D = D("0.005")

EPF_RULES = [
    EpfRule(date(2014, 9, 1), D("15000")),
    EpfRule(date(2026, 9, 17), D("25000")),   # S.O. 5109(E), 17 Sep 2026
]

@dataclass(frozen=True)
class EsiRule:
    effective_from: date
    ceiling: D = D("21000")
    ee_rate: D = D("0.0075")
    er_rate: D = D("0.0325")

ESI_RULES = [EsiRule(date(2019, 7, 1))]

@dataclass(frozen=True)
class PtSlab:
    min_wage: D               # inclusive
    max_wage: D | None        # inclusive; None = open-ended
    monthly: D
    february: D | None = None

PT_RULES = {  # (state, gender) -> slabs; "*" = any gender
    ("MH", "M"): [PtSlab(D("0"), D("7500"), D("0")),
                  PtSlab(D("7500.01"), D("10000"), D("175")),
                  PtSlab(D("10000.01"), None, D("200"), D("300"))],
    ("MH", "F"): [PtSlab(D("0"), D("25000"), D("0")),
                  PtSlab(D("25000.01"), None, D("200"), D("300"))],
    ("KA", "*"): [PtSlab(D("0"), D("24999.99"), D("0")),
                  PtSlab(D("25000"), None, D("200"), D("300"))],
}

def rule_on(rules, day: date):
    return max((r for r in rules if r.effective_from <= day),
               key=lambda r: r.effective_from)

# ---------------- wages ----------------
def code_wages(basic_da_ra: D, gross: D) -> D:
    """Code on Wages s.2(y) 50% proviso, simplified: if excluded items exceed
    half of total remuneration, the excess is added back to wages."""
    excluded = gross - basic_da_ra
    return basic_da_ra + max(D("0"), excluded - gross / 2)

# ---------------- EPF ----------------
@dataclass
class EpfResult:
    epf_wage: D
    eps_wage: D
    ee: D
    eps: D
    er_epf: D
    edli: D
    admin: D
    audit: list = field(default_factory=list)

def epf_month(year, month, monthly_wage: D, paid_from=1, paid_to=None,
              member_from: date | None = None, eps_from: date | None = None,
              higher_wages=False, vpf_rate=D("0")) -> EpfResult:
    """Split the month at every rule change (and membership date), cap each
    segment at ceiling x segment_days / days_in_month, then round once."""
    dim = calendar.monthrange(year, month)[1]
    paid_to = paid_to or dim
    first, last = date(year, month, 1), date(year, month, dim)
    cuts = {first}
    cuts |= {r.effective_from for r in EPF_RULES if first < r.effective_from <= last}
    cuts |= {d for d in (member_from, eps_from) if d and first < d <= last}
    cuts = sorted(cuts) + [last + timedelta(days=1)]

    epf_wage = eps_wage = D("0")
    audit = []
    for start, nxt in zip(cuts, cuts[1:]):
        seg_days = (nxt - start).days
        paid = len([d for d in range(start.day, nxt.day if nxt <= last else dim + 1)
                    if paid_from <= d <= paid_to])
        if member_from and start < member_from:
            continue
        rule = rule_on(EPF_RULES, start)
        earned = monthly_wage * paid / dim
        cap = rule.wage_ceiling * seg_days / dim
        seg_epf = earned if higher_wages else min(earned, cap)
        seg_eps = min(earned, cap) if (eps_from and start >= eps_from) else D("0")
        epf_wage += seg_epf
        eps_wage += seg_eps
        audit.append(f"{start}..{nxt - timedelta(days=1)} ceiling={rule.wage_ceiling} "
                     f"epf={seg_epf:.2f} eps={seg_eps:.2f}")

    r = rule_on(EPF_RULES, last)
    ee = to_rupee(epf_wage * (r.ee_rate + vpf_rate))   # VPF: employee only
    er_total = to_rupee(epf_wage * r.ee_rate)
    eps = to_rupee(eps_wage * r.eps_rate)
    return EpfResult(epf_wage.quantize(D("0.01")), eps_wage.quantize(D("0.01")),
                     ee, eps, er_total - eps,
                     to_rupee(epf_wage * r.edli_rate), to_rupee(epf_wage * r.admin_rate),
                     audit)

# ---------------- ESI ----------------
def esi_month(day: date, esi_wage: D, wage_at_period_start: D):
    """Eligibility is tested at the start of the contribution period
    (1 Apr / 1 Oct, or on joining); a mid-period raise doesn't end coverage."""
    r = rule_on(ESI_RULES, day)
    if wage_at_period_start > r.ceiling:
        return D("0"), D("0")
    return up_to_rupee(esi_wage * r.ee_rate), up_to_rupee(esi_wage * r.er_rate)

# ---------------- Professional Tax ----------------
def pt_month(state: str, gender: str, month: int, wage: D) -> D:
    slabs = PT_RULES.get((state, gender)) or PT_RULES.get((state, "*"), [])
    for s in slabs:
        if wage >= s.min_wage and (s.max_wage is None or wage <= s.max_wage):
            return s.february if (month == 2 and s.february is not None) else s.monthly
    return D("0")

def epf_arrears(year, month, old_wage: D, new_wage: D, **kw) -> dict:
    """Re-run the ORIGINAL wage month under the rules of that month."""
    a, b = epf_month(year, month, old_wage, **kw), epf_month(year, month, new_wage, **kw)
    return {k: getattr(b, k) - getattr(a, k) for k in ("ee", "eps", "er_epf")}

if __name__ == "__main__":
    always = date(2000, 1, 1)                      # long-standing EPS member
    sep = epf_month(2026, 9, D("20000"), eps_from=always)
    print("Sep 2026, wage 20,000:", sep.epf_wage, sep.ee, sep.eps, sep.er_epf, sep.edli)
    for line in sep.audit:
        print("   ", line)
    oct_ = epf_month(2026, 10, D("25000"), eps_from=always)
    print("Oct 2026, wage 25,000:", oct_.ee, oct_.eps, oct_.er_epf, oct_.edli, oct_.admin)
    j = epf_month(2026, 10, D("24000"), paid_from=20, member_from=date(2026, 10, 20),
                  eps_from=date(2026, 10, 20))
    print("Joined 20 Oct, wage 24,000:", j.epf_wage, j.ee, j.eps, j.er_epf)
    print("Arrears 14k->18k for Sep:", epf_arrears(2026, 9, D("14000"), D("18000"), eps_from=always))
    print("ESI on 18,450:", esi_month(date(2026, 10, 31), D("18450"), D("18450")))
    print("PT MH(M) 12,000 Feb:", pt_month("MH", "M", 2, D("12000")),
          "| KA 25,000 Oct:", pt_month("KA", "*", 10, D("25000")))

Running python3 statutory.py:

Sep 2026, wage 20,000: 17333.33 2080 1444 636 87
    2026-09-01..2026-09-16 ceiling=15000 epf=8000.00 eps=8000.00
    2026-09-17..2026-09-30 ceiling=25000 epf=9333.33 eps=9333.33
Oct 2026, wage 25,000: 3000 2083 917 125 125
Joined 20 Oct, wage 24,000: 9290.32 1115 774 341
Arrears 14k->18k for Sep: {'ee': Decimal('288'), 'eps': Decimal('200'), 'er_epf': Decimal('88')}
ESI on 18,450: (Decimal('139'), Decimal('600'))
PT MH(M) 12,000 Feb: 300 | KA 25,000 Oct: 200

The September result (â‚¹2,080 employee share, â‚¹1,444 EPS and â‚¹636 EPF) matches EPFO's Scenario C (â‚¹2,080.00, â‚¹1,443.87 and â‚¹636.13) once it is rounded to rupees. The October row matches EPFO's full-month table exactly.

Tests that pin you to the regulator's examples

# test_statutory.py
from datetime import date
from decimal import Decimal as D
from statutory import epf_month, esi_month, pt_month, code_wages

OLD = date(2000, 1, 1)          # "has been an EPS member for ages"
NEW = date(2026, 9, 17)         # revised ceiling effective date

def test_sep_2026_scenario_c_capped_member():   # Scenario C
    r = epf_month(2026, 9, D("20000"), eps_from=OLD)
    assert r.epf_wage == D("17333.33")
    assert (r.ee, r.eps, r.er_epf, r.edli) == (2080, 1444, 636, 87)

def test_october_full_month_table():            # EPFO FAQ Q13
    assert [(r.ee, r.eps, r.er_epf, r.edli, r.admin) for r in (
        epf_month(2026, 10, D("20000"), eps_from=OLD),
        epf_month(2026, 10, D("25000"), eps_from=OLD),
        epf_month(2026, 10, D("35000")),           # not an EPS member
    )] == [(2400, 1666, 734, 100, 100), (3000, 2083, 917, 125, 125),
           (3000, 0, 3000, 125, 125)]

def test_pt_slabs():
    assert pt_month("MH", "M", 10, D("10000")) == 175     # MH: only wages that "exceed" 10,000 pay 200
    assert pt_month("MH", "M", 2, D("10001")) == 300      # February
    assert pt_month("MH", "F", 10, D("25000")) == 0
    assert pt_month("KA", "*", 10, D("25000")) == 200     # "25,000 and above"
    assert pt_month("KA", "*", 10, D("24999")) == 0

$ pytest -q test_statutory.py
3 passed in 0.01s

The regulator's worked examples make cheap, trustworthy fixtures, and old tests should keep passing for old dates after a rule changes.

6. Design tips

Treat rules as data. Rates, ceilings and PT slabs belong in versioned configuration, not in if branches. A rule change should be a data migration with a review, not a code deploy.
Give every rule a date range. Each rule needs an effective_from date, and lookups should be based on the wage period, not the date the payroll runs. September 2026 shows why: the same month had two ceilings, and October arrears for August need August's rules. Payroll platforms like TankhaPay handle these rules as effective-dated configuration.
Keep an audit trail. Store the rule version, segment breakdown, unrounded intermediate values and rounding mode alongside each result, as the audit list does above. EPFO's own checklist for the ceiling change tells employers to keep a clear audit trail of the calculations.
Round once, at the edge. Use Decimal and keep paise throughout the calculation. Then apply each scheme's rounding rule only to the final contribution.
Keep eligibility separate from calculation. ESI coverage is a per-period state and EPS membership is a per-employee state. Store both as data instead of inferring them from this month's salary.

Things this example does not cover

Exempted PF trusts.
International workers.
Contract labour handled through the principal employer.
PT for states other than Maharashtra and Karnataka.
Gender-specific or other state-specific PT exemptions beyond those shown above.
A joiner whose start date falls inside September 2026.

Disclaimer: This article is general information for software developers and is not legal, tax or compliance advice. Statutory rates, ceilings and slabs change, so verify against the official notifications and your compliance advisers before using any figure in production payroll.

References

Gazette of India, S.O. 5109(E), 17 Sept 2026 (â‚¹25,000 wage ceiling): https://cdnbbsr.s3waas.gov.in/s36547884cea64550284728eb26b0947ef/uploads/2026/09/202609241085718651.pdf
PIB, Cabinet approves enhancement of EPFO wage ceiling (16 Sept 2026): https://www.pib.gov.in/PressReleasePage.aspx?PRID=2310811&lang=2&reg=48
Ministry of Labour & Employment / PIB press release on the 17 Sept 2026 effective date: https://www.labour.gov.in/static/uploads/2026/09/4f607a88c5342aeb980c6b999997caab.pdf
PIB Kolkata, EPFO raises wage ceiling; EPS maximum rises to â‚¹2,083 (23 Sept 2026): https://www.pib.gov.in/PressReleasePage.aspx?PRID=2313829&lang=2&reg=48
EPFO, FAQs: Revision of EPFO Statutory Wage Ceiling from â‚¹15,000 to â‚¹25,000 (Sept 2026), published by EPFO
PIB, Four Labour Codes effective 21 Nov 2025: https://www.pib.gov.in/PressReleasePage.aspx?PRID=2192463
The Code on Wages, 2019 (section 2(y)): https://www.labour.gov.in/static/uploads/2025/06/c328da14bbb15fc4ad571dc33e7a4ab3.pdf
ESIC, Contribution rates and contribution periods: https://esic.gov.in/contribution
ESIC, Coverage and wage limit: https://esic.gov.in/coverage
Gazette of India, S.O. 2351(E), 8 May 2026 (ESI continuation within a contribution period): https://www.labour.gov.in/static/uploads/2026/05/e10c5bf2f9ba640316b5190a6e7d9300.pdf
Lok Sabha Unstarred Question 1345 (27 July 2026), ESI wage ceiling: https://sansad.in/getFile/lsapps/loksabhaquestions/annex/188/AU1345_TBAsOH.pdf
Maharashtra GST Department, Profession Tax rate schedule: https://www.mahagst.gov.in/en/profession-tax-and-other-rate-schedule
Karnataka Commercial Taxes Department, Professional Tax portal (February â‚¹300 notice): https://ptax.karnataka.gov.in/ptemployer

Written by the team at TankhaPay, a global HRMS and AI recruitment platform.