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")
}Response
{
"input": {
"salary": 5000,
"bonus": 1000,
"epfRate": "11%",
"socsoType": "both",
"eisType": "auto"
},
"calculations": {
"pcbDeduction": 180, // PCB (tax) deduction
"epfEmployeeDeduction": 660, // Employee EPF contribution
"socsoEmployee": 20, // Employee SOCSO contribution (capped at RM4,000)
"eisEmployee": 8, // Employee EIS contribution (capped at RM4,000)
"epfEmployer": 780, // Employer EPF contribution
"socsoEmployer": 70, // Employer SOCSO contribution (capped at RM4,000)
"eisEmployer": 8, // Employer EIS contribution (capped at RM4,000)
"hrdf": 25, // HRDF contribution (0.5% of salary)
"totalEarnings": 6000, // Total earnings (salary + bonus)
"totalDeductions": 868, // Total deductions
"netIncome": 5132 // Net income after deductions
}
}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 databasedata- 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 payslipuserId- 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"
API Version History
Changelog
v1.0.0 (Current) - April 2025
- Initial API release
- Added calculation endpoints for Malaysian payslip standards
- Implemented user and payslip storage with Deno KV
- Added authentication with API keys