How do I calculate PAYE for a South African employee?

PAYE comes from the SARS personal income tax tables plus the age rebates. GET /calc/net-salary applies the current tables and employee UIF to a gross monthly salary; POST /v1/answers/payroll does the whole payroll in one call, returning PAYE, pension deductibility, the medical scheme credit, both UIF sides, take-home pay and total employer cost.

Does it include employer UIF and total cost to company?

Yes. UIF is charged at 1 percent from the employee and 1 percent from the employer up to the contribution ceiling, and the payroll answer returns the employer's total cost alongside the employee's take-home.

Is the pension contribution cap applied?

Yes. Retirement fund contributions are deductible up to 27.5 percent of the greater of remuneration or taxable income, capped annually. The cap and the tax-free savings limits live in the retirement-limits series with their citations.

What is the BCEA earnings threshold for?

Above it, the Basic Conditions of Employment Act working-time protections (overtime, ordinary hours, rest periods) fall away. The payroll answer flags which side of the threshold an employee sits on.

How current are the tax tables?

They are re-verified daily against the official source. Every response carries source_url, effective_date, last_confirmed and a stale flag, and a series past its expected update declares itself stale rather than pretending.

zaref / docs / payroll-api

South African payroll API

Everything a payroll run needs for one South African employee, as cited JSON: the SARS income tax tables PAYE is calculated from, the UIF contribution ceiling, the BCEA earnings threshold and the retirement contribution caps, each with its official source and effective date.

The calculators turn those tables into numbers (PAYE, net take-home, gross-up, UIF, medical scheme credits, travel allowance and company car fringe benefit), and POST /v1/answers/payroll returns the entire payroll breakdown for one employee in a single call, including the employer's cost and an optional minimum-wage check.

Series

GET /v1/income-tax

SARS personal income tax brackets, rebates and thresholds for the current SA tax year, the tables PAYE is calculated from.

$0.005 per call · updates: annual (National Budget) · effective 2026-03-01 · history at /v1/income-tax/history ($0.01)

GET /v1/uif-oid

UIF contribution remuneration ceiling and OID (COIDA) earnings threshold.

$0.005 per call · updates: annual · effective 2026-03-01 · history at /v1/uif-oid/history ($0.01)

GET /v1/bcea-thresholds

The BCEA earnings threshold, which working-time protections fall away above it, the earnings definition and related LRA/EEA effects.

$0.005 per call · updates: annual (March/April gazette) · effective 2026-05-01 · history at /v1/bcea-thresholds/history ($0.01)

GET /v1/retirement-limits

Retirement contribution deduction cap, tax-free savings limits, retirement and withdrawal lump-sum tax tables, living-annuity thresholds.

$0.005 per call · updates: annual (Budget) · effective 2026-03-01 · history at /v1/retirement-limits/history ($0.01)

Calculators

GET /calc/income-tax

SA personal income tax (PAYE) for the current tax year: annual and monthly tax, effective and marginal rate, SARS age rebates applied.

Parameters: annual, age

$0.01 per call · example: /calc/income-tax?annual=750000&age=40

GET /calc/net-salary

Net take-home from a gross monthly salary: PAYE plus employee UIF at the current tables.

Parameters: monthly, age

$0.01 per call · example: /calc/net-salary?monthly=50000&age=35

GET /calc/net-to-gross

Gross monthly salary required to net a target take-home amount, at the current tax tables.

Parameters: net_monthly, age

$0.01 per call · example: /calc/net-to-gross?net_monthly=40000&age=35

GET /calc/uif

Monthly UIF contribution (employee 1% + employer 1%) at the current earnings ceiling.

Parameters: monthly_salary

$0.01 per call · example: /calc/uif?monthly_salary=25000

GET /calc/medical-tax-credit

Medical scheme (medical aid) fees tax credit plus the additional medical expenses tax credit from qualifying out-of-pocket costs.

Parameters: members, dependants, out_of_pocket_annual, taxable_income, has_65_plus_or_disability

$0.01 per call · example: /calc/medical-tax-credit?members=1&dependants=2&out_of_pocket_annual=15000&taxable_income=500000

GET /calc/travel-allowance

PAYE inclusion and monthly tax impact of a fixed travel allowance under the 80/20 rule.

Parameters: monthly_allowance, business_use_80_percent, annual_income, age

$0.01 per call · example: /calc/travel-allowance?monthly_allowance=8000&annual_income=720000

GET /calc/company-car

Company car fringe benefit: monthly taxable value (3.5%/3.25%) and PAYE impact.

Parameters: vehicle_value, maintenance_plan, business_use_80_percent, annual_income, age

$0.01 per call · example: /calc/company-car?vehicle_value=450000&maintenance_plan=true&annual_income=720000

Task-shaped answers

One call returns the whole answer, composed from the same audited tables as the series and calculators above, with every source cited. Cheaper than fetching the tables and doing the arithmetic yourself, and there is nothing to keep in sync.

POST /v1/answers/payroll

One employee's monthly payroll: PAYE with age rebates, pension deductibility (27.5% / R430k cap), medical scheme credit, employee and employer UIF, take-home pay, employer cost, BCEA earnings-threshold flag and an optional minimum-wage check.

$0.10 per call · JSON body, e.g. {"monthly_gross":40000,"age":34,"pension_percent":7.5,"medical_members":2,"hours_per_week":45}

POST /v1/answers/income-tax

Full income-tax answer for one taxpayer: tax due after age rebates and medical scheme credits, effective rate, monthly PAYE equivalent, with the component calculations included.

$0.05 per call · JSON body, e.g. {"annual":480000,"age":34,"medical_members":2}

How agents pay

No account, no API key. Paid endpoints reply HTTP 402 with exact payment requirements; an x402 client pays USDC on Base (about two seconds to settle) and retries automatically. Invalid input is rejected free with a 400 before any payment is challenged. See the x402 quickstart.

Questions

How do I calculate PAYE for a South African employee?: PAYE comes from the SARS personal income tax tables plus the age rebates. GET /calc/net-salary applies the current tables and employee UIF to a gross monthly salary; POST /v1/answers/payroll does the whole payroll in one call, returning PAYE, pension deductibility, the medical scheme credit, both UIF sides, take-home pay and total employer cost.
Does it include employer UIF and total cost to company?: Yes. UIF is charged at 1 percent from the employee and 1 percent from the employer up to the contribution ceiling, and the payroll answer returns the employer's total cost alongside the employee's take-home.
Is the pension contribution cap applied?: Yes. Retirement fund contributions are deductible up to 27.5 percent of the greater of remuneration or taxable income, capped annually. The cap and the tax-free savings limits live in the retirement-limits series with their citations.
What is the BCEA earnings threshold for?: Above it, the Basic Conditions of Employment Act working-time protections (overtime, ordinary hours, rest periods) fall away. The payroll answer flags which side of the threshold an employee sits on.
How current are the tax tables?: They are re-verified daily against the official source. Every response carries source_url, effective_date, last_confirmed and a stale flag, and a series past its expected update declares itself stale rather than pretending.

South African repo and prime rate API South Africa fuel price API SARS income tax tables API South Africa VAT API and free calculator South African public holidays API