Gross-to-net payroll tax, as an API.

Withholding is not one hard problem. It's a matrix of small ones that multiply.

Two W-4 generations

Pre-2020 and 2020-onward take entirely separate calculation paths. The Step 2 checkbox selects a different table.

Supplemental wages

Flat rate or aggregate method, with a higher mandatory rate above the annual threshold.

Wage bases that move

Social Security stops at a base that changes every year. Medicare never stops, and adds a surtax above a threshold with no employer match.

Local jurisdictions

Pennsylvania Act 32: thousands of taxing jurisdictions, PSD codes, resident versus non-resident rates, withhold-the-higher-of. Ohio: roughly 600 municipalities plus JEDDs and school districts, courtesy withholding, occasional-entrant thresholds. Kentucky occupational fees by city and county. Indiana county tax keyed to residence on a fixed date.

Reciprocity

Withhold for residence instead of work location — but only if the employee filed the right exemption certificate. Get it backwards and you have withheld for the wrong state all year.

The one that breaks every hand-rolled engine. A deduction's treatment differs per tax and per state.

A correction, kept visible

This page previously listed the nine states with no income tax withholding as free coverage. That was wrong. Several still take employee-side deductions, and a paycheck that omits them looks complete and is wrong — the exact failure this is meant to prevent.

Illustrative. The engine does not exist, so this is a design sketch, not documentation. Jurisdictions are resolved codes, not names — v1 does not turn an address into a jurisdiction, and a locality string could not drive Ohio school-district or PA Act 32 withholding if it tried. Money is strings, never floats.

POST /v1/calculate

{
  "check_date":     "2026-02-13",
  "pay_frequency":  "biweekly",
  "ruleset":        "2026.02.1",
  "employee": {
    "residence":     { "state": "OH", "municipality": "3910",
                       "school_district": "2103" },
    "work":          [{ "state": "OH", "municipality": "2246",
                        "percent": 100, "days_in_period": 10 }],
    "federal_w4":    { "version": 2020, "filing_status": "single",
                       "step2_checkbox": true, "dependents": 2000.00,
                       "other_income": 0.00, "deductions": 0.00,
                       "extra": 0.00 },
    "state_certs":   { "OH": { "form": "IT-4", "exemptions": 1 } },
    "reciprocity":   []
  },
  "employer":  { "sui_state": "OH", "sui_rate": "0.0270" },
  "earnings":  [{ "type": "regular", "amount": "3200.00" },
                { "type": "bonus",   "amount": "5000.00",
                  "supplemental_method": "flat" }],
  "pre_tax":   [{ "type": "401k", "amount": "480.00" }],
  "ytd": {
    "federal": { "wages": "22400.00", "withheld": "2180.00" },
    "fica":    { "ss_wages": "21980.00", "medicare_wages": "21980.00" },
    "sui":     { "OH": "21980.00" },
    "local":   { "OH:2246": "21980.00" }
  }
}

And the half that matters — every tax carries the base it was computed on, what was excluded from that base, the rule, and whether that rule is verified against an authority or against one person's reading of it.

200 OK

{
  "ruleset":  "2026.02.1",
  "engine":   "0.4.2",
  "taxes": [
    {
      "id": "us.federal.income",
      "side": "employee",
      "taxable_base": "2510.00",
      "excluded": [{ "type": "401k", "amount": "480.00" },
                   { "type": "sec125", "amount": "210.00" }],
      "amount": "241.00",
      "method": "percentage",
      "cite": "IRS Pub 15-T (2026), Worksheet 1A",
      "confidence": "authority"
    },
    {
      "id": "us.fica.social_security",
      "side": "employee",
      "taxable_base": "2990.00",
      "excluded": [{ "type": "sec125", "amount": "210.00" }],
      "amount": "185.38",
      "cite": "IRC 3121(a)(5)(D) - 401(k) deferrals are FICA wages",
      "confidence": "authority"
    },
    {
      "id": "us.oh.municipality.2246",
      "side": "employee",
      "taxable_base": "2510.00",
      "amount": "50.20",
      "cite": "Dublin OH municipal code, 2.0% - author-derived",
      "confidence": "derived"
    }
  ],
  "warnings": [
    "OH:2246 non-resident: verify 20-day occasional-entrant threshold"
  ]
}

IRS Publication 15-T publishes worked examples for both W-4 generations. Some state employer guides publish a handful. Those become golden test vectors — public, CC0, citation on every case, and useful to a competitor, which is the point. A test suite only its author can run proves nothing.

Every vector is labelled authority-sourced or author-derived, and pass rates are reported separately, never blended. That distinction matters most where this is hardest: Ohio's ~600 municipalities and Pennsylvania's Act 32 matrix publish almost no official worked examples, so vectors covering them are one person's reading of the rules. A high score there measures careful transcription, not correctness — and you should be told that rather than sold past it.

What would actually verify an engine is a parallel run against an incumbent's real paystubs for a quarter. Nothing here substitutes for that.

You should not have to trust a vendor's accuracy claim. You should be able to read the failures.

The vector repository is being transcribed now. It publishes with the first batch — the schema, runner and methodology are written; the numbers are copied by hand from the source, never generated.

Nothing is built. No signup, no waitlist theatre.

Intended pricing, so you can answer usefully rather than politely: banded on employees calculated per month, published as a table, in the region of $99 to $1,500 per month. No "contact us". If that number makes this a no, that is exactly the reply worth sending.

If you run payroll infrastructure and have opinions about Ohio municipal tax, I want to hear them. Especially if you evaluated Zeal's Abacus before it was withdrawn.

Vishal Rana · LabStack LLC