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
- OpenAPI 3.1 (JSON)
Every endpoint, typed.
https://www.havahr.com/openapi.json
- OpenAPI 3.1 (YAML)
Same document, YAML.
https://www.havahr.com/api/openapi.yaml
- Calculator catalog
All tools with input schemas.
https://www.havahr.com/api/v1/calculators
- MCP endpoint
Streamable HTTP, no install.
https://www.havahr.com/api/mcp
- MCP manifest
Discovery handshake.
https://www.havahr.com/.well-known/mcp
- Agent index
llms.txt site index.
https://www.havahr.com/llms.txt
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 ID | Endpoint | When to use |
|---|---|---|
| calculate_malaysia_payroll | POST /api/v1/calculators/malaysia-payroll | A user asks what a Malaysian salary nets after statutory deductions, or wants a payslip breakdown. |
| calculate_epf | POST /api/v1/calculators/epf | Only the EPF/KWSP employee and employer contribution is needed. |
| calculate_socso | POST /api/v1/calculators/socso | Only the SOCSO/PERKESO contribution is needed, including the age 60+ Category 2 split. |
| calculate_eis | POST /api/v1/calculators/eis | Only the EIS/SIP contribution is needed, including eligibility by citizenship and age. |
| calculate_skbbk | POST /api/v1/calculators/skbbk | Checking the Lindung 24 Jam (SKBBK) employee deduction for a specific wage month, including opt-out handling. |
| calculate_pcb | POST /api/v1/calculators/pcb | Estimating monthly income tax withholding (PCB/MTD) for a salary and tax category. |
| calculate_employer_cost | POST /api/v1/calculators/employer-cost | A user asks what an employee really costs the employer, or is budgeting a new hire. |
| calculate_overtime | POST /api/v1/calculators/overtime | Working out Employment Act 1955 overtime, rest-day, or public-holiday pay, and the 45h/104h compliance limits. |
| calculate_leave_proration | POST /api/v1/calculators/leave-proration | Prorating annual leave for a mid-year joiner or leaver, or for an unpaid-leave adjustment. |
| check_employment_act_coverage | POST /api/v1/calculators/employment-act-coverage | Deciding whether Employment Act 1955 entitlements apply to a given employee. |
| calculate_hrd_corp_levy | POST /api/v1/calculators/hrd-corp-levy | Working 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" }
]
}
}| Code | HTTP | Meaning |
|---|---|---|
| invalid_json | 400 | The request body was not valid JSON. |
| not_found | 404 | No endpoint or calculator matches the path. |
| method_not_allowed | 405 | The endpoint exists but not for this HTTP method. |
| not_acceptable | 406 | No representation matches the Accept header. |
| unsupported_media_type | 415 | Content-Type was not application/json. |
| invalid_request | 422 | The body failed schema validation. See error.details. |
| internal_error | 500 | Unexpected 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.