💰 How Payroll Works

A complete guide to payroll processing in HRSanad — from first setup to final bank transfer.

🌍 The Big Picture

Think of payroll as a factory. Every month, raw materials go in (employee details, attendance, leaves, loans) and a finished product comes out (a salary slip for every employee, and a file that tells the bank who gets paid how much).

🧱 Pay Components — The Building Blocks

A salary is not just one number. It is built from many smaller pieces called pay components. Each component is either something the employee earns or something that gets deducted.

The three types of components

How a component's value is calculated

Method	How it works	Example
fixed	A flat amount every month, always the same.	Transport Allowance = AED 800
pct_basic	A percentage of the employee's basic salary.	Housing = 25% of Basic → 25% × 10,000 = AED 2,500
pct_gross	A percentage of total gross earnings (all earnings combined).	Bonus = 5% of Gross
pct_component	A percentage of one specific other component.	Extra Allowance = 10% of Housing Allowance
formula	A custom mathematical expression evaluated by the system.	(basic * 0.3) + 500

🏗️ The Three-Layer Salary Setup

HRSanad uses a smart three-layer system to decide each employee's pay components. You don't have to set up every allowance for every employee individually — defaults flow down automatically.

🔄 The Payroll Run — Step by Step

Every month you create a Payroll Run. Think of it as a container that holds every employee's salary slip for that month. A run always follows a strict sequence of statuses — you cannot skip steps or go backwards.

Detailed walkthrough of each step

1. Create the Run (DRAFT)

   Go to Payroll → Runs → New Run. Choose the year, month, and which company's employees to include. The run is created in draft status — it's just an empty shell at this point. No numbers yet.

   API call: POST /v1/payroll/runs with { year, month, company_id }

2. Calculate (DRAFT → CALCULATED)

   Click Calculate. The system now works through every active employee one by one and produces a salary slip for each. This is the most important step — see the next section for exactly how the math works.

   API call: POST /v1/payroll/runs/:id/calculate

   After this, you can view all the salary slips and check for any errors.

3. Review the Slips

   Open the run and browse each department's slips. Look for anything unusual — an employee with zero salary, an unexpectedly high overtime figure, a missing loan deduction. Fix the root data (attendance, pay components) if needed, then recalculate.

   API call: GET /v1/payroll/runs/:id/slips (supports department filter & pagination)

4. Approve (CALCULATED → APPROVED)

   Once you're satisfied, click Approve. This represents the HR Manager's or Finance Manager's sign-off that the numbers are correct. After this, the slips are locked for editing.

   API call: POST /v1/payroll/runs/:id/approve

5. Finalize (APPROVED → FINALIZED)

   Finalization confirms that the payroll is ready for payment. It's a second confirmation layer (e.g., CFO sign-off) before the bank files are generated.

   API call: POST /v1/payroll/runs/:id/finalize

6. Generate WPS File (FINALIZED → LOCKED)

   Click Generate WPS. The system creates a SIF file (Standard Input Format) which is the official UAE Wage Protection System format accepted by all UAE banks. Once generated, the run is locked — no more changes of any kind.

   API call: POST /v1/payroll/runs/:id/generate-wps

   You upload this SIF file to your bank's portal and the bank processes the transfers.

7. Generate Journal Voucher (Optional)

   If your company uses accounting software (Oracle GL, SAP, Temenos T24, or any system accepting CSV), click Generate JV. This creates a journal entry CSV with payroll costs broken down by cost centre, department, and pay component — ready to import into your accounts.

   API call: POST /v1/payroll/runs/:id/generate-jv

🧮 How the Calculation Works

When you hit Calculate, the engine processes every eligible employee in this order:

1. Fetch the employee's pay components

   Using the three-layer system described above, the engine builds a final list of all applicable pay components and their values for this employee.

2. Get attendance data from TNA

   From the Time & Attendance module, the engine reads how many working days were in the month, how many the employee was present, any absent days, and total overtime hours.

   • Working days: total scheduled working days in the month (weekends and holidays excluded)
   • Paid days: working days minus absent days
   • Absent days: days with no attendance and no approved leave
3. Calculate each earning component

   For each earning component, compute its value using the method (fixed, pct_basic, formula, etc.). Then pro-rate it if the employee was absent:

   pro_rated_amount = (component_value / working_days) × paid_days

   If the employee worked all days, paid_days = working_days, so they get the full amount.

4. Add Overtime Pay

   Overtime is calculated from TNA data. UAE Labour Law rates:

   • Weekday overtime: 1.5× the hourly basic rate
   • Public holiday overtime: 2× the hourly basic rate

   hourly_rate = basic_salary / (working_days_in_month × 8)
   ot_pay = ot_hours × hourly_rate × 1.5

5. Compute total earnings

   total_earnings = sum of all earning components + ot_pay

6. Apply deductions

   Each deduction component is calculated (same methods as earnings). Loan instalments are automatically fetched from the Loans module for active loans and added as deductions.

   total_deductions = sum of all deduction components + loan_instalments

7. Calculate net salary

   net_salary = total_earnings − total_deductions

8. Compute employer costs (not paid to employee)

   • Gratuity accrual: how much gratuity liability built up this month (see Gratuity section)
   • Leave accrual: simplified as basic_salary / 12 per month
   • Employer contributions: any employer-side components (e.g., pension)

📄 The Salary Slip — Anatomy

Each employee gets a salary slip (also called a payslip) that shows the complete breakdown. Here is what a typical slip looks like:

🏅 End-of-Service Gratuity (UAE Law)

Under UAE Labour Law (Federal Decree 33/2021), every employee who completes at least one year of service is entitled to an end-of-service gratuity payment when they leave.

The gratuity formula

daily_rate   = basic_salary / 30
gratuity     = days_per_year × daily_rate × years_in_this_band

The number of days_per_year depends on total service length, split into bands:

Example — 7 years of service, Basic Salary = AED 10,000

Monthly Gratuity Accrual on the Payslip

Every month, payroll computes how much gratuity liability grew that month. This appears on the payslip as an informational figure (not deducted from the employee):

monthly_accrual = annual_gratuity_for_full_service / years_of_service / 12

🏦 WPS — Wage Protection System

In the UAE, all private-sector companies are legally required to pay salaries through the Wage Protection System (WPS), regulated by the Central Bank of UAE (CBUAE) and the Ministry of Human Resources.

WPS works like this:

1. HRSanad generates a SIF file (Standard Input Format) — a structured text file listing every employee's IBAN, the amount to pay, and the payment date.
2. You upload the SIF file to your bank's corporate online portal.
3. The bank processes the file and transfers money to each employee's bank account on the specified date.
4. The bank reports back to CBUAE confirming that salaries were paid. If a company fails to pay on time, CBUAE can issue fines or freeze the company's work permit applications.

📒 Journal Voucher (JV Export)

After payroll is finalized, Finance needs to post the payroll costs to the company's accounting system. HRSanad generates a Journal Voucher (JV) CSV that can be imported directly into:

• Oracle General Ledger
• SAP (BAPI format)
• Temenos T24
• Any system that accepts a generic CSV journal import

The JV breaks down payroll costs by:

• Cost Centre — which department or project bears the cost
• Pay Component — basic salary, housing, transport, etc., each on its own line
• Debit / Credit — standard double-entry accounting format

✅ How to Run Payroll — Month-End Checklist

🔌 API Quick Reference

Action	Method	Endpoint	Required Status
List runs	GET	/v1/payroll/runs	Any
Create run	POST	/v1/payroll/runs	—
Get run details	GET	/v1/payroll/runs/:id	Any
Calculate slips	POST	/v1/payroll/runs/:id/calculate	draft
View slips	GET	/v1/payroll/runs/:id/slips	calculated+
View single slip	GET	/v1/payroll/runs/:id/slips/:slipId	calculated+
Approve run	POST	/v1/payroll/runs/:id/approve	calculated
Finalize run	POST	/v1/payroll/runs/:id/finalize	approved
Generate WPS (SIF)	POST	/v1/payroll/runs/:id/generate-wps	finalized
Generate JV CSV	POST	/v1/payroll/runs/:id/generate-jv	finalized
List employee pay comps	GET	/v1/payroll/employees/:id/pay-components	—
Add pay component override	POST	/v1/payroll/employees/:id/pay-components	—
Remove pay component override	DELETE	/v1/payroll/employees/:id/pay-components/:pcId	—

📋 Key Business Rules

Rule	Description
BR-PAY-001	Monthly payroll supports mid-month processing via a separate run_type (for new joiners or separations mid-month).
BR-PAY-004	Payroll finalization requires workflow approval — the status machine enforces the sequence and cannot be bypassed.
BR-PAY-005	WPS file can only be generated when the run is in approved or finalized status.
Gratuity daily rate	Always basic_salary / 30. Never use 26. This is UAE Labour Law.
Gratuity slabs	Always read from finance.gratuity_slabs table. Never hardcoded.
Overtime rates	1.5× on weekdays, 2× on public holidays (UAE Labour Law Article 67).
Minimum service for gratuity	Employee must have completed at least 1 full year of service. Less than 1 year = AED 0 gratuity.