API Documentation

This API allows you to calculate payslip deductions, preview payslips, save user data, and generate downloadable payslips according to Malaysian standards.

Current API Version: v1

Authentication

All API requests require an API key sent as the X-API-Key header.

You can generate an API key by registering for an account at /api/register and then accessing your API dashboard.

Endpoints

POST

/api/v1/calculate

Calculate deductions based on salary and other parameters.

Request Body

{
  "salary": 5000,          // Required: Monthly basic salary
  "bonus": 1000,           // Optional: Bonus amount (default: 0)
  "epfRate": "11%",        // Optional: EPF employee rate (default: "11%", options: "0%", "9%", "5.5%", "11%")
  "socsoType": "both",     // Optional: SOCSO scheme type (default: "both", options: "both", "injury", "none")
  "eisType": "auto",       // Optional: EIS calculation (default: "auto", options: "auto", "none")
  "includePCB": true,     // Optional: include PCB deduction (default: true)
  "includeEPF": true,      // Optional: include EPF (default: true)
  "includeSOCSO": true,    // Optional: include SOCSO (default: true)
  "includeEIS": true       // Optional: include EIS (default: true)
}

Response

{
  "input": {
    "salary": 5000,
    "bonus": 1000,
    "epfRate": "11%",
    "socsoType": "both",
    "eisType": "auto"
  },
  "calculations": {
    "pcbDeduction": 180,             // PCB (tax) approximation
    "epfEmployeeDeduction": 660,     // Employee EPF 11%
    "socsoEmployee": 24.75,           // PERKESO schedule (wage ceiling RM6,000)
    "eisEmployee": 10,                // EIS 0.2% (wage ceiling RM6,000)
    "epfEmployer": 720,              // Employer EPF 12% (salary + bonus > RM5,000)
    "socsoEmployer": 86.25,           // PERKESO schedule
    "eisEmployer": 10,               // EIS 0.2%
    "hrdf": 25,                      // HRDF 0.5% of salary
    "totalEarnings": 6000,
    "totalDeductions": 874.75,
    "netIncome": 5125.25
  }
}

POST

/api/v1/preview-payslip

Generate a preview of the payslip in HTML or JSON format.

Request Body

{
  // Required fields
  "companyName": "Tech Sdn Bhd",     // Company name
  "employeeName": "John Doe",        // Employee name
  "basicSalary": 5000,               // Basic salary

  // Optional fields - if not provided, these will be calculated automatically
  "bonus": 1000,                     // Bonus amount
  "companyAddress": "123 Main St",   // Company address
  "employeePosition": "Developer",   // Employee position
  "employeeId": "123456",            // IC/Passport number
  "epfNumber": "123456",             // EPF number
  "pcbNumber": "123456",             // PCB number
  "residenceStatus": "resident",     // Residence status
  "typeOfResident": "Normal",        // Resident type
  "marriedStatus": "Single",         // Marital status
  "dependentChildren": 0,            // Number of dependent children
  "month": "January",                // Month
  "year": "2023",                    // Year
  "issueDate": "2023-01-31",         // Issue date
  "epfRate": "11%",                  // EPF rate
  "socsoType": "both",               // SOCSO type
  "eisType": "auto"                  // EIS type
}

Query Parameters

format - Response format (default: "html", options: "html", "json")

Response

format=html: Returns an HTML document with the payslip preview.

format=json: Returns JSON data with payslip details and calculations.

GET

/api/v1/download-payslip

Generate a downloadable payslip.

Query Parameters

id - Payslip ID stored in KV database
data - JSON string with payslip data (fallback if id is not provided)

Response

Returns an HTML document formatted as a payslip, ready for printing or saving as PDF.

POST

/api/v1/save-user

Save user information to the KV database.

Request Body

{
  "name": "John Doe",      // Required: User's name
  "email": "john@example.com",  // Required: User's email (used as unique identifier)
  "phone": "0123456789"    // Required: User's phone number
}

Response

{
  "success": true  // Boolean indicating if the operation was successful
}

GET

/api/v1/save-user

Retrieve user information from the KV database.

Query Parameters

email - User's email address (required)

Response

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "0123456789",
  "createdAt": "2023-08-01T12:34:56.789Z"
}

POST

/api/v1/save-payslip

Save payslip data to the KV database.

Request Body

{
  "userId": "user@example.com",  // Required: User's email to associate with this payslip
  "data": {                     // Required: Payslip data (same format as preview-payslip)
    "companyName": "Tech Sdn Bhd",
    "employeeName": "John Doe",
    "basicSalary": 5000,
    // ... other payslip fields
  }
}

Response

{
  "success": true,
  "id": "a1b2c3d4e5f6..."  // Unique ID for the saved payslip
}

GET

/api/v1/save-payslip

Retrieve payslip data from the KV database.

Query Parameters

id - Payslip ID to retrieve a specific payslip
userId - User's email to retrieve all payslips for a user

Response (id parameter)

{
  "id": "a1b2c3d4e5f6...",
  "userId": "user@example.com",
  "data": {
    // Payslip data
  },
  "createdAt": "2023-08-01T12:34:56.789Z"
}

Response (userId parameter)

[
  {
    "id": "a1b2c3d4e5f6...",
    "userId": "user@example.com",
    "data": {
      // Payslip data
    },
    "createdAt": "2023-08-01T12:34:56.789Z"
  },
  {
    "id": "g7h8i9j0k1l2...",
    "userId": "user@example.com",
    "data": {
      // Payslip data
    },
    "createdAt": "2023-08-15T15:30:45.123Z"
  }
  // ... more payslips
]

Examples

Curl Examples

Calculate deductions

curl -X POST http://localhost:8000/api/v1/calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "salary": 5000,
    "bonus": 1000,
    "epfRate": "11%",
    "socsoType": "both",
    "eisType": "auto"
  }'

Save user data

curl -X POST http://localhost:8000/api/v1/save-user \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "0123456789"
  }'

Save payslip

curl -X POST http://localhost:8000/api/v1/save-payslip \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "userId": "john@example.com",
    "data": {
      "companyName": "Tech Sdn Bhd",
      "employeeName": "John Doe",
      "basicSalary": 5000,
      "bonus": 1000
    }
  }'

Download a payslip by ID

curl -X GET "http://localhost:8000/api/v1/download-payslip?id=a1b2c3d4e5f6..." \
  -H "X-API-Key: YOUR_API_KEY"

Changelog

v1.1.0 — March 2026

Edit & Reuse payslips from history; summary/edit page
Optional deductions: EPF, SOCSO, EIS, PCB (checkboxes and API flags)
EPF employer: 12% when salary > RM5,000, 13% otherwise
SOCSO/EIS: PERKESO schedule, wage ceiling RM6,000
Previous payslips step removed from wizard
Print layout: Employer Contributions stay on one line

v1.0.0 — Initial release

Calculate, preview, save, and download payslips
Malaysian EPF, SOCSO, EIS, PCB calculations
API key authentication; user and payslip storage (Deno KV)