Request an advance, review the approval chain, record disbursement and track repayments.
Access
request_salary_advance enables your own requests and cancellation while pending. manage_salary_advance enables management, decisions within approval scope, manual repayments, statistics and policy configuration. disburse_salary_advance is separately required to record disbursement.
Requesting an advance
For employees, the request starts the approval process; it does not transfer money. For managers, approval, recording the payment and checking repayment are separate tasks.
Open Request Advance. Eligibility shows the policy maximum (a percentage of base salary), outstanding balance and available amount. Enter the amount, repayment months and optional reason; the form estimates the monthly deduction.
The server checks base salary, policy percentage, maximum repayment months and minimum tenure. It also blocks a second active advance while one is pending, approved, disbursed or repaying. The available-amount calculation subtracts outstanding balances, but a positive displayed amount does not override that one-active-advance rule.
Policy and approval
Salary Advance Policy configures the maximum percentage, maximum repayment months, minimum tenure and approval mode. Modes are Auto-Approve, Single Approver and Approval Chain.
Steps can resolve to a direct manager, department head, role holder or specific employee, with fallback configuration and amount thresholds. A configured escalation time is stored on a step; it should not be treated as a guarantee that a timer will reassign it automatically.
Approvers use Pending My Approval. The current step must be decided before the next step. The final approval sets the approved amount and monthly deduction; the approved amount cannot exceed the request. Rejection ends the request and skips remaining steps. A person cannot approve or reject their own request.
If no configured approver can be resolved, the resolver attempts the company's senior escalation approver. If that also fails, the implementation can return an empty chain and auto-approve the request. Check actual employee reporting lines and resolved approval steps when configuring a policy; selecting Approval Chain alone does not guarantee a human decision.
The request timeline records step decisions, comments and timestamps. The requester can cancel only while pending.
Recording disbursement
Disburse records the payment reference and repayment start date (first of next month when omitted). This action records that an advance was paid; it does not send an M-Pesa or bank transfer itself.
When the payroll provider is available, disbursement creates the recurring SALARY_ADV deduction. Failure to create that deduction prevents disbursement from being recorded. The schedule has a start and end date derived from the repayment term. Confirm the payment separately and check the resulting deduction.
Repayment
Completed payroll emits the actual salary-advance deduction amount. The repayment listener records it in a ledger, updates the repaid balance and changes disbursed advances to repaying. Duplicate payroll events for the same advance and pay run do not double-credit repayment.
Record Payment with manage_salary_advance records an off-payroll repayment. Once outstanding is within one cent of zero, the advance settles and the service attempts to deactivate the payroll deduction.
Reversing payroll unwinds that run's payroll repayments, restores the advance balance/status and attempts to reactivate a deduction that settlement disabled. Manual repayments are not removed by payroll reversal.
| Status | Meaning |
|---|---|
| Pending | Awaiting approval |
| Approved | Approved, not yet recorded as disbursed |
| Rejected | Declined |
| Disbursed | Disbursement recorded |
| Repaying | Repayment has been recorded |
| Settled | Balance cleared within the settlement tolerance |
| Cancelled | Withdrawn while pending |
When payroll trims an installment
The payroll engine's configured deduction cap defaults to two-thirds of gross. It reduces custom post-tax deductions if necessary, reducing salary-advance recovery first. Statutory, PAYE and pre-tax lines are not reduced, so the implementation cannot guarantee a fixed minimum take-home in every case.
The advance ledger credits only the amount actually recovered. A trimmed installment leaves more outstanding; the deduction schedule is not automatically extended or increased to collect the shortfall. Review remaining balance and the deduction end date, and arrange an appropriate follow-up repayment. The configured cap and this behavior describe the implementation, not legal advice.
See the Payroll Workflow Guide for the full calculation and reversal flow.
Frequently asked questions
I have an available amount but cannot make another request. Why? Only one active advance is allowed. Check for an existing pending, approved, disbursed or repaying request before starting another.
Can I withdraw a request? You can cancel your own request while it is pending. Once it has progressed, ask the responsible administrator to review its state rather than treating cancellation as a refund.
My advance is approved. Has it been paid? Approval is a decision on the request. Confirm the actual payment separately; Disburse records its reference and repayment schedule but does not initiate a transfer.
Where should I check a repayment difference? Compare the payslip deduction with the advance repayment ledger and remaining balance. Check whether the payroll deduction cap reduced the amount and whether the recurring deduction has reached its end date.