Payroll Management

Get List of Paystubs

GET /api/paystubs

Description:

Returns a list of paystubs for the authenticated company.

Headers:

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Query Parameters:

Name	Type	Description
company_id	integer (optional)	ID of the company. Defaults to the authenticated company ID.
user_id	integer (optional)	Filter paystubs by a specific user (employee) ID.
transaction_id	string (optional)	Filter paystubs by a specific transaction ID.
status	string (optional)	Filter paystubs by their status (paid, unpaid, etc.).
page	integer (optional)	Page number for pagination.
per_page	integer (optional)	Number of items per page (default is 10).

Response:

200

{
    "message": "Paystubs retrieved successfully",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": 1,
                "user_id": 1,
                "company_id": 1,
                "pay_period_start": "2023-01-01",
                "pay_period_end": "2023-01-15",
                "taxable_income": 5000.00,
                "reimbursements": 1000.00,
                "other_allowances": 500.00,
                "gross_pay": 6500.00,
                "net_pay": 4500.00,
                "tax_withheld": 500.00,
                "pension_contribution": 200.00,
                "nhf_contribution": 100.00,
                "nhis_contribution": 50.00,
                "other_deductions": 150.00,
                "status": "paid",
                "transaction_id": "COMPANYCODE-ABC123",
                "created_at": "2023-01-16T10:00:00Z",
                "updated_at": "2023-01-16T10:00:00Z",
                "user": {
                    "id": 1,
                    "first_name": "John",
                    "last_name": "Doe",
                    "email": "[e-mail]"
                    // ... other user fields
                },
                "contribution": {
                    "id": 1,
                    "employee_id": 1,
                    "company_id": 1,
                    "pay_period_start": "2023-01-01",
                    "pay_period_end": "2023-01-15",
                    "employee_pension_contribution": 200.00,
                    "employer_pension_contribution": 300.00,
                    "nhf_contribution": 100.00,
                    "pit_contribution": 500.00,
                    // ... other contribution fields
                    "custom_contribution_records": [
                        {
                            "id": 1,
                            "contribution_id": 1,
                            "user_id": 1,
                            "name": "Health Insurance",
                            "employee_contribution": 50.00,
                            "employer_contribution": 100.00,
                            "created_at": "2023-01-16T10:00:00Z",
                            "updated_at": "2023-01-16T10:00:00Z"
                        }
                        // ... other custom contributions
                    ]
                }
            }
            // ... other paystubs
        ],
        "first_page_url": "http://example.com/api/paystubs?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "http://example.com/api/paystubs?page=1",
        "next_page_url": null,
        "path": "http://example.com/api/paystubs",
        "per_page": 20,
        "prev_page_url": null,
        "to": 1,
        "total": 1
    }
}

400

{
    "error": "Validation error message here..."
}

401

{
    "error": "Unauthorized"
}

403

{
    "error": "You do not have permission to access this company's paystubs."
}

404

{
    "error": "Paystub or company not found."
}

Create a New Paystub

POST /api/paystubs

Description:

Creates a new paystub for the authenticated company.

Headers:

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body:

Name	Type	Description
id	string	ID of the user
pay_period_start	string	The start date of the pay period
pay_period_end	string	The end date of the pay period
taxable_income	number	The taxable amount for the period
reimbursements	number	Reimbursement for the period
other_allowances	number	Other non taxable pay for the period
company_id	integer (optional)	ID of the company. Defaults to the authenticated company ID.

Request example:

{
    "paystubs": [
        {
            "id": 1,
            "pay_period_start": "2023-01-01",
            "pay_period_end": "2023-01-15",
            "taxable_income": 5000.00,
            "reimbursements": 1000.00,
            "other_allowances": 500.00
        }
    ]
}

Response example:

201

{
    "message": "Paystub processing completed",
    "created_paystubs": [
        {
            "paystub": {
                "id": 1,
                "user_id": 1,
                "company_id": 1,
                "pay_period_start": "2023-01-01",
                "pay_period_end": "2023-01-15",
                "taxable_income": 5000.00,
                "reimbursements": 1000.00,
                "other_allowances": 500.00,
                "gross_pay": 6500.00,
                "net_pay": 4500.00,
                "tax_withheld": 500.00,
                "pension_contribution": 200.00,
                "nhf_contribution": 100.00,
                "nhis_contribution": 50.00,
                "other_deductions": 150.00,
                "status": "unpaid",
                "transaction_id": "COMPANYCODE-ABC123",
                "created_at": "2023-01-16T10:00:00Z",
                "updated_at": "2023-01-16T10:00:00Z"
            },
            "custom_contributions": [
                {
                    "id": 1,
                    "contribution_id": 1,
                    "user_id": 1,
                    "name": "Health Insurance",
                    "employee_contribution": 50.00,
                    "employer_contribution": 100.00,
                    "created_at": "2023-01-16T10:00:00Z",
                    "updated_at": "2023-01-16T10:00:00Z"
                }
                // ... other custom contributions
            ]
        },
        {
            "paystub": {
                "id": 2,
                "user_id": 2,
                "company_id": 1,
                "pay_period_start": "2023-01-01",
                "pay_period_end": "2023-01-15",
                "taxable_income": 6000.00,
                "reimbursements": 0.00,
                "other_allowances": 0.00,
                "gross_pay": 6000.00,
                "net_pay": 4800.00,
                "tax_withheld": 600.00,
                "pension_contribution": 240.00,
                "nhf_contribution": 120.00,
                "nhis_contribution": 60.00,
                "other_deductions": 180.00,
                "status": "unpaid",
                "transaction_id": "COMPANYCODE-DEF456",
                "created_at": "2023-01-16T10:00:00Z",
                "updated_at": "2023-01-16T10:00:00Z"
            },
            "custom_contributions": [
                {
                    "id": 2,
                    "contribution_id": 2,
                    "user_id": 2,
                    "name": "Retirement Fund",
                    "employee_contribution": 60.00,
                    "employer_contribution": 120.00,
                    "created_at": "2023-01-16T10:00:00Z",
                    "updated_at": "2023-01-16T10:00:00Z"
                }
                // ... other custom contributions
            ]
        }
    ],
    "failed_paystubs": [
        // ... any paystubs that failed to be created, along with error messages
    ]
}

401

{
    "error": "Unauthorized"
}

400

{
    "error": "Bad Request"
}