PayrollToolsPricingBlog

HavaHR

Developer & agent documentation

A free, unauthenticated JSON API and MCP server for Malaysian statutory payroll maths β€” EPF, SOCSO, EIS, SKBBK, PCB, employer cost, overtime, leave proration, Employment Act coverage, and the HRD Corp levy. Same engine as the product.

When to use this API

  • A task needs Malaysian take-home pay after EPF, SOCSO, EIS, SKBBK, and PCB.
  • Someone is budgeting a hire and needs the full employer cost, not just the salary.
  • A payslip deduction needs checking against the official KWSP or PERKESO tables.
  • Overtime, rest-day, or public-holiday pay needs working out under the Employment Act 1955.
  • Annual leave needs prorating for a mid-year joiner or leaver.
  • You need to know whether Employment Act 1955 entitlements apply to an employee.
  • You need the HRD Corp (HRDF) levy for a payroll.

When not to use it

  • Reading or writing a customer’s payroll, leave, or employee records β€” the public API is calculation-only.
  • Non-Malaysian statutory calculations.
  • Filing with KWSP, PERKESO, or LHDN. Results are estimates and must be confirmed before filing.

Machine-readable entry points

Authentication

None. The calculator API is free and public, needs no key or registration, performs no writes, and reads no customer data. Requests are POST with Content-Type: application/json, and every monetary value is Malaysian Ringgit.

Each operation’s operationId matches its MCP tool name, so one definition works for both REST function calling and MCP. A GET on any calculator endpoint returns its JSON Schema without running it.

Calculators

Operation IDEndpointWhen to use
calculate_malaysia_payrollPOST /api/v1/calculators/malaysia-payrollA user asks what a Malaysian salary nets after statutory deductions, or wants a payslip breakdown.
calculate_epfPOST /api/v1/calculators/epfOnly the EPF/KWSP employee and employer contribution is needed.
calculate_socsoPOST /api/v1/calculators/socsoOnly the SOCSO/PERKESO contribution is needed, including the age 60+ Category 2 split.
calculate_eisPOST /api/v1/calculators/eisOnly the EIS/SIP contribution is needed, including eligibility by citizenship and age.
calculate_skbbkPOST /api/v1/calculators/skbbkChecking the Lindung 24 Jam (SKBBK) employee deduction for a specific wage month, including opt-out handling.
calculate_pcbPOST /api/v1/calculators/pcbEstimating monthly income tax withholding (PCB/MTD) for a salary and tax category.
calculate_employer_costPOST /api/v1/calculators/employer-costA user asks what an employee really costs the employer, or is budgeting a new hire.
calculate_overtimePOST /api/v1/calculators/overtimeWorking out Employment Act 1955 overtime, rest-day, or public-holiday pay, and the 45h/104h compliance limits.
calculate_leave_prorationPOST /api/v1/calculators/leave-prorationProrating annual leave for a mid-year joiner or leaver, or for an unpaid-leave adjustment.
check_employment_act_coveragePOST /api/v1/calculators/employment-act-coverageDeciding whether Employment Act 1955 entitlements apply to a given employee.
calculate_hrd_corp_levyPOST /api/v1/calculators/hrd-corp-levyWorking out the HRD Corp (HRDF) levy and the training budget it funds.

Example

Request

curl -sS https://www.havahr.com/api/v1/calculators/malaysia-payroll \
  -H 'Content-Type: application/json' \
  -d '{"grossSalary": 5000, "employeeAge": 30, "isMalaysian": true}'

Response

{
  "tool": "calculate_malaysia_payroll",
  "currency": "MYR",
  "disclaimer": "Estimates only β€” not official advice. ...",
  "result": {
    "grossSalary": 5000,
    "epfEmployee": 550,
    "socsoEmployee": 24.75,
    "eisEmployee": 9.9,
    "pcb": 43.35,
    "netPay": 4364.25,
    "totalEmployeeDeductions": 635.75,
    "totalEmployerContributions": 736.75
  }
}

Errors

Errors are always JSON with a stable code, a human-readable message, an actionable hint, and a docs link. Validation failures list each offending field in details.

Validation error

{
  "error": {
    "code": "invalid_request",
    "message": "Request body failed validation.",
    "hint": "Fix the fields listed in details. The full input schema is at GET /api/v1/calculators/malaysia-payroll.",
    "docs": "https://www.havahr.com/developers",
    "details": [
      { "field": "grossSalary", "message": "Too small: expected number to be greater than 0" }
    ]
  }
}
CodeHTTPMeaning
invalid_json400The request body was not valid JSON.
not_found404No endpoint or calculator matches the path.
method_not_allowed405The endpoint exists but not for this HTTP method.
not_acceptable406No representation matches the Accept header.
unsupported_media_type415Content-Type was not application/json.
invalid_request422The body failed schema validation. See error.details.
internal_error500Unexpected server-side failure. Safe to retry.

MCP

The same calculators are available over the Model Context Protocol β€” remotely over Streamable HTTP, or locally over stdio from npm.

Remote (Streamable HTTP)

{
  "mcpServers": {
    "havahr-calculators": {
      "url": "https://www.havahr.com/api/mcp"
    }
  }
}

Local (stdio via npm)

{
  "mcpServers": {
    "havahr-calculators": {
      "command": "npx",
      "args": ["-y", "@havahr/mcp-calculators"]
    }
  }
}

Per-client setup guides for Cursor, Claude, ChatGPT/Codex, VS Code, Windsurf, and Zed are on the Malaysia Payroll MCP page.

Markdown representations

Pages that publish a markdown variant serve it through Accept content negotiation and at a .md URL. Both responses set Vary: Accept.

Markdown

curl -sS -H 'Accept: text/markdown' https://www.havahr.com/developers
curl -sS https://www.havahr.com/developers.md

Disclaimer

Results are estimates from the same engine as the HavaHR product. They are not official advice β€” confirm with KWSP, PERKESO, or LHDN before filing.