Ghana Payroll API

What it does

An open-source API that works out PAYE, SSNIT Tier 1 and Tier 2, and net pay from the official GRA and SSNIT rate tables, including the new bands from 1 September 2026. Every result shows its working and names the official table it used, and rate changes are versioned so old payslips recalculate exactly.

The problem

Small businesses and HR tools in Ghana still calculate payroll in spreadsheets, and tax bands change. Mistakes cost money and trust.

What you get

How to use it

Run the API next to your HR or accounting app and send it amounts in pesewas (GHS 5,000.00 is 500000). Store the rate_tables it returns with each payslip so you can always show your working.

git clone https://github.com/Jacksonoseikojo1122/ghana-payroll-api.git
cd ghana-payroll-api && npm install
npm start   # http://localhost:8788, with a calculator at /

curl -X POST http://localhost:8788/v1/payslip -H 'content-type: application/json' -d '{
  "period": "2026-10",
  "basic_salary": 500000,
  "allowances": [{ "name": "Transport", "amount": 100000 }]
}'
# net_pay 468925 (GHS 4,689.25), tax.paye 103575, ssnit.tier1 67500, ssnit.tier2 25000

const res = await fetch(`${PAYROLL_URL}/v1/payslip`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ period: "2026-10", basic_salary: 500000 }),
});
const slip = await res.json();
if (res.status === 422) throw new Error(slip.error); // no official table for that period

console.log(slip.net_pay / 100);   // net pay in cedis
console.log(slip.working);         // every step, in words
console.log(slip.rate_tables);     // which GRA and SSNIT tables were used

res = requests.post(f"{PAYROLL_URL}/v1/payroll-runs",
    headers={"Authorization": f"Bearer {KEY}", "Idempotency-Key": "acme-2026-10"},
    json={"period": "2026-10", "employees": employees})
run = res.json()   # same key again returns this run, never a second one
csv = requests.get(f"{PAYROLL_URL}/v1/payroll-runs/{run['id']}/payslips.csv",
    headers={"Authorization": f"Bearer {KEY}"}).text

Documentation

• Getting started Install, first payslip, gross-up and payroll runs
• Integration guide Node.js, Python and PHP clients, and what every field means
• How it works Every PAYE and SSNIT rule, with rounding
• Rate tables Official sources, versioning and known gaps
• OpenAPI spec Every endpoint, for Postman, Insomnia or code generators

Features

• PAYE from GRA's Act 1178 bands (from 1 September 2026), with bonus, overtime, non-resident and casual-worker rules
• SSNIT on basic salary within the 2026 limits, split into employee, employer, Tier 1 and Tier 2
• Every step of the working in the response, with links to the official GRA and SSNIT sources
• Integer pesewas throughout, rounded per band, so the numbers always add up
• Versioned rate tables: no official table for a period means an error, never a guess
• Gross-up from a target net pay, and payroll runs with idempotency keys and CSV export

What building it covers

• Exact money logic
• Versioned business rules
• Audit trails
• Idempotent batch jobs

Stack

• TypeScript
• Node.js
• Hono
• Zod
• PostgreSQL
• SQLite
• Vitest
• Docker

Questions