Prepare, calculate, review and complete payroll, then reconcile payments separately.
Access and preparation
Payroll requires the PAYROLL licence. Read endpoints use view_payroll; preparing and processing runs uses manage_payroll. Approval and M-Pesa disbursement use approve_payroll. Assign the read and action permissions needed by each operator.
Before calculation, review employee salaries, earnings, deductions, approved attendance, approved unpaid leave and the holiday calendar. Salary structures carry pay frequency; the calculator can convert salary frequency, but pay runs must be monthly. Other run frequencies are rejected at calculation.
Eligible employees include active, on-leave, and employees terminated during or after the period start. Salary lookup can fall back to the employee's base salary. Inspect skipped employees instead of assuming every employee was paid.
Workflow
Before your first run
| Check | Where to start | What to review |
|---|---|---|
| Employee pay | Employee profile and salary settings | Salary amount, frequency, hire date and any termination date |
| Earnings and deductions | Payroll → Salary Setup | Allowances, bonuses, recurring deductions and their effective dates |
| Overtime | Attendance policies | An active overtime rule and the intended payment basis |
| Working time | Time Entries | Approved hours and outstanding correction requests |
| Leave and holidays | Leave requests and attendance policies | Approved unpaid leave and the holiday calendar |
| Approval access | Roles & Permissions | Who prepares the run and who can approve it |
Create and calculate
Open Payroll → Pay Runs, then New Pay Run. Give the run a recognisable name, such as “September 2026 Payroll”. Set the period start and end to the month being paid, and the payment date to the intended payment day. Use Monthly frequency. Leave Supplementary off for an ordinary monthly run.
Creating the run saves a draft; it does not calculate pay or send money. Open the run's detail page to calculate it, then follow the status sequence below.
draft -> calculating -> calculated -> reviewing -> approved -> processing -> completed
|
v
reversed
- Create a run with name, period start/end, payment date, frequency and optional Supplementary flag. Regular runs cannot overlap another non-reversed regular run. Supplementary permits overlap; it does not calculate a correction delta automatically.
- Calculate the draft. The service gathers salary, earnings, deductions, attendance, leave, holidays and effective tax configuration, then stores employee line items and totals. Recalculation replaces previous items.
- Preview, when useful, computes projections without saving pay-run items. Review skipped employees here too.
- Submit for Review from calculated status. Inspect line items, totals and variance flags.
- Approve from reviewing status with
approve_payroll. When the company enables the separate-approver setting, the run's creator cannot approve it. This setting defaults off. - Process the approved run. Processing runs asynchronously, using the background worker where configured or the in-process path. Refresh/poll until completed. Completion produces payslips and journal entries; it is not proof that employees have received money.
Per-employee calculation validation failures, including negative net, are reported as skipped employees while other employees continue. Systemic failures still abort; if all employees fail calculation, the run returns to draft. Always check employee count and skipped reasons before approval.
Review and recalculation
Variance flags compare against the most recent completed run: gross/net changes over 10%, basic salary over 5%, and deductions over 15%. A first-time employee has no prior comparison. Flags are advisory.
Compare gross against salaries and earnings, deductions against the actual breakdown, net against funding requirements, and employer cost against gross plus employer contributions. There is no reliable fixed deduction percentage for every employee.
To recalculate a reviewing run, return it to calculated and then draft. An approved run can return to reviewing before processing. Processing failure returns the run to approved for retry.
Payslips, accounting and payment
Processing creates payslip snapshots and balanced journal entries. The payslip number uses the period-end date and a sequence (PS-YYYYMMDD-0001). Display/PDF serving hides zero-value line items while preserving the stored snapshot. Employees can access payslips through self-service; payroll also has download/email actions.
Journal entries cover salary expense, employer NSSF/Housing Levy/NITA expense, PAYE, NSSF, SHIF, Housing Levy, NITA and other deduction liabilities, and net pay payable.
Pay employees separately through the bank EFT file or M-Pesa disbursement. M-Pesa requires a completed run and approve_payroll; it is not automatically initiated by Process.
Reversals and corrections
Reverse a completed run with a reason. The original payslips and journal entries remain; reversal posts offsetting journal entries and marks the run reversed. Pending or successful M-Pesa disbursements block reversal. Reconcile payment attempts before deciding how to correct a paid run.
A supplementary run allows an overlapping period and selected employees, but runs the regular calculation pipeline. It does not subtract a previously paid salary automatically. Review the full proposed amounts before using it for back pay or corrections; do not assume that fixing a salary and rerunning pays only the difference.
How gross-to-net works
- Convert the salary frequency, then prorate salary using active calendar days divided by total period calendar days. Monetary rounding happens after applying the full ratio.
- Subtract approved unpaid leave using the prorated salary divided by working days in the active sub-period. Working-day counts use the rule's working-days-per-week setting and holidays.
- Add fixed/percentage earnings and any payable overtime. Non-taxable earnings remain in gross payout but are excluded from chargeable earnings used for statutory contributions and PAYE.
- Subtract employee statutory pre-tax contributions and eligible custom pre-tax deductions to calculate taxable income.
- Calculate PAYE, then apply personal and qualifying insurance relief.
- Subtract post-tax deductions, apply the configured deduction cap, and compute net and employer costs.
Overtime
Payroll reads approved attendance. An active overtime rule is required for overtime pay, even when recorded overtime hours exist. Its normal daily hours and working-days-per-week determine expected period hours and the hourly rate.
premium_only adds hourly rate times (multiplier minus one) times overtime hours. full_rate adds hourly rate times the full multiplier times hours. Rest-day mode is configurable; Saturday/Sunday classification is only the weekend default. See Time & Attendance.
Implemented Kenya defaults
These tables describe the fallback code in the Kenya PAYE engine, not a guarantee of current legal requirements. Effective company configuration can override tax brackets and statutory rates; verify the saved values used for the run.
You do not need to add tax brackets or statutory rates to follow these defaults. The NSSF limit is stored with the date it took effect, and a pay run uses the limit in force on its period end date.
Payroll checks your setup before every calculation and on the Salary Setup page:
- It will not calculate on a setup that cannot give a correct result: a custom tax band set that does not start at 0, has a gap or an overlap, or has no last band without an upper limit; a rate above 1 (type 6% as
0.06); a negative amount. The message says what to correct. - It warns when a rate you added differs from the default, and when your rate is dated before a change to the default. The warning shows both values and both dates, and it stays on the pay run for whoever reviews and approves it.
- A rate you added stays in force until you change or delete it.
| Monthly PAYE band as configured (KES) | Rate |
|---|---|
| 0 to 24,000 | 10% |
| 24,001 to 32,333 | 25% |
| 32,334 to 500,000 | 30% |
| 500,001 to 800,000 | 32.5% |
| 800,001 and above | 35% |
| Contribution | Employee default | Employer default |
|---|---|---|
| NSSF | 6%, capped at KES 6,480 monthly; pre-tax | 6%, same cap |
| SHIF | 2.75%, minimum KES 300 monthly; pre-tax | None |
| Housing Levy | 1.5%; pre-tax | 1.5% |
| NITA | None | KES 50 monthly |
Personal relief defaults to KES 2,400 monthly. Insurance relief uses qualifying premiums, at 15% capped at KES 5,000 monthly; SHIF is not itself the insurance-relief premium base. Custom pre-tax pension/retirement/provident deductions share a KES 30,000 monthly cap; PRMF uses KES 15,000 and mortgage/owner-occupier interest KES 30,000.
Worked example: KES 100,000 monthly gross
This example uses the defaults above for a full month, with all earnings taxable, no custom deductions and no qualifying insurance premiums. It illustrates the calculation; use your actual run breakdown when company rates or employee inputs differ.
| Step | Amount (KES) |
|---|---|
| Gross pay | 100,000.00 |
| Employee NSSF | −6,000.00 |
| SHIF | −2,750.00 |
| Employee Housing Levy | −1,500.00 |
| Taxable income | 89,750.00 |
| First 24,000 at 10% | 2,400.00 |
| Next 8,333 at 25% | 2,083.25 |
| Remaining 57,417 at 30% | 17,225.10 |
| Gross PAYE | 21,708.35 |
| Personal relief | −2,400.00 |
| PAYE after relief | 19,308.35 |
| Total employee deductions | 29,558.35 |
| Net pay | 70,441.65 |
The company also pays KES 6,000 employer NSSF, KES 1,500 employer Housing Levy and KES 50 NITA. Total employer cost is KES 107,550.00. These employer contributions are additional company costs, not further deductions from the net pay above.
Deduction cap
The fallback cap ratio is two-thirds of gross, configurable through an effective DEDUCTION_CAP statutory-rate row. If total deductions exceed it, the engine reduces custom post-tax lines, salary-advance recovery first. It does not reduce statutory, PAYE or pre-tax lines. Consequently the cap does not guarantee one-third take-home when protected lines already exceed the ratio.
Stored breakdowns and repayment events use the amount actually deducted. A trimmed amount is not automatically added to a later period. Review any outstanding salary-advance balance and its scheduled deduction end date. See Salary Advances.
Frequently asked questions
An employee is missing from the calculated run. What should I check? Review the skipped-employee reasons, employee status and employment dates, and salary configuration. A run can finish calculating even when individual employees were skipped. Resolve those issues and recalculate before approval.
Why is recorded overtime missing from pay? Check that the attendance is approved, an overtime rule is active and its payment basis and multipliers match your policy. Recorded overtime hours alone do not establish overtime pay.
Can I change a run after review? Return it through the allowed statuses to draft before recalculating. Recalculation replaces its previous items. For a completed run, use the reversal/correction workflow described above.
Does a completed run mean everyone has been paid? No. Completion creates payslips and accounting entries. Reconcile your bank or M-Pesa payment separately before treating salaries as received.
Why was a deduction smaller than the configured amount? Inspect the payslip breakdown and deduction-cap handling. A capped recovery can leave an outstanding amount that needs follow-up; it is not automatically collected next month.
Where do I get the monthly statutory schedules? Open Payroll → Statutory Reports after completion. Check the payment month, which determines the runs included. See Reports & Statutory Filings.