Skip to content

Module 12: Payroll & WPS Processing

The Payroll module (/payroll/*) is a rules-based compensation engine designed to automate complex salary calculations, enforce UAE Wages Protection System (WPS) compliance, compute End-of-Service Gratuity, and generate accounting GL postings.

🎯 Core Components

1. Salary Rules (/payroll/rules)

  • Categories: BASIC, ALLOWANCE, GROSS, DEDUCTION, NET, COMP_CONTRIB (Company Contribution).
  • Computation Methods:
  • Fixed (amount_fixed): A flat currency amount added to the payslip line.
  • Percentage (amount_percentage): A percentage of the employee's contract base wage.
  • Python Code (amount_python_code): Dynamic Python expression evaluated in a sandboxed context (contract, employee, payslip, categories).
  • Condition Python (condition_python): Optional evaluation expression; if result = False, the rule is skipped.
  • EOSB Flag (is_eosb): Marks rules included in UAE End-of-Service Gratuity calculations.
  • GL Accounting Link: Each rule maps to a ChartOfAccounts ledger for automatic journal entry creation upon payslip confirmation.

2. Salary Structures (/payroll/structures)

  • Collections of Salary Rules grouped by employee category (e.g. Executive Structure, Sales Structure, General Staff Structure).

3. Payroll Batch Processing (/payroll/run)

  • Batch Lifecycle: PENDING → GENERATED → APPROVED → PAID.
  • Automatic Batch Generation:
  • Selects all active employees where in_payroll=True with an active contract.
  • Computes payslips, evaluating rules in sequence.
  • Unpaid Leave Auto-Deduction: Scans approved unpaid leave days during the pay period and automatically calculates (contract.wage / 30) × unpaid_days as a DEDUCTION line (UNPAID_LEAVE).
  • Accounting Posting (confirm_payslip):
  • Automatically posts a JournalEntry (type: MISC, status: POSTED).
  • Debits: BASIC + ALLOWANCE expense GL accounts.
  • Credits: DEDUCTION accounts & Salaries Payable liability GL account.

4. UAE WPS SIF File Generation

  • Generates a compliant UAE MOMRAH-standard SIF CSV file for bank submission:
  • Header Row (SCR): EmployerUID, BankRoutingCode, FileDate, FileTime, SalaryMonth (MMYYYY), EmployeeCount, TotalSalary, Currency (AED).
  • Body Rows (EDR): Labour Card / Visa Number, AgentID, IBAN, StartDate, EndDate, Days Worked, Fixed Income, Variable Income, Deductions, Net Total.

5. UAE End-of-Service Benefit (Gratuity) Engine

  • Based on UAE Labour Law Decree-Law 33/2021:
  • Entitlement minimum: 1 year of continuous service.
  • Service 1–5 Years: 21 days' basic salary per year.
  • Service > 5 Years: 30 days' basic salary per year for subsequent years.
  • Maximum Cap: 2 years' (24 months') basic salary total.
  • Calculation formula: Daily Basic = Contract Basic Wage / 30.

💡 Step-by-Step Instructions

Running Monthly Payroll & Exporting WPS File

  1. Open Payroll → Process Payroll (/payroll/run).
  2. Click Create Batch, select pay period (e.g., April 2026), and set start/end dates.
  3. Click Generate Batch Payslips. The system calculates payslips for all eligible staff, applying allowances, deductions, and unpaid leave calculations.
  4. Review batch totals and inspect individual payslip lines.
  5. Click Approve Batch. The system posts the payroll Journal Entry to GL.
  6. Click Download WPS SIF File and save the .sif file for your corporate online banking portal!