Withholding Tax on Professional Payments - hmislk/hmis GitHub Wiki
Withholding Tax on Professional Payments
When HMIS pays a doctor or consultant their professional fees, the system can withhold a percentage of the payment as Withholding Tax (WHT), in line with local revenue regulations. This article explains what you see on the screen, when WHT is deducted, and how the three calculation modes behave.
The administrator sets the WHT limit, percentage, and default calculation mode. See Admin — Withholding Tax Configuration for the configuration side. This article is for the cashier or finance user who runs the payment.
Where WHT appears
WHT shows up on these screens:
- Initiate Professional Payments (OPD All-Due flow —
/opd/professional_payments/payment_staff_bill.xhtml). - Inward Professional Payment (
/inward/inward_bill_professional_payment.xhtml). - Inward Surgery Payment (
/inward/inward_bill_surgery_payment.xhtml). - Channel — Paying a Doctor (the channel-side flow).
The per-shift OPD pay screen (/opd/pay_doctor.xhtml) does not display the WHT panel inline; if you need to inspect and tune WHT for a per-shift payment, use the All-Due flow instead.
A dedicated Withholding Tax Report is at /reports/financialReports/wht.xhtml (see Reports below).
The Payment Details panel
When you settle a professional payment, the screen has a settings sub-panel on the left and a totals sub-panel on the right.
Left sub-panel — settings:
| Field | Notes |
|---|---|
| WHT Calculation | The calculation mode for this run. If the configuration option Allow User To Select Whether To Pay Withholding Tax During Professional Payments is on, this is a dropdown with three modes. If it is off, the value is shown as a fixed badge — you cannot change it. |
| Payment Method | Cash, Cheque, Bank Transfer, etc. WHT itself is not affected by payment method. |
| Total Payment Completed for this month | Read-only. The amount this professional has been paid this calendar month at the current institute. Used by the Depending On Payments mode. |
| Withholding Cutoff | Read-only configuration value. The threshold (default 100 000) above which WHT kicks in under Depending On Payments mode. |
| Withholding Percentage | Read-only configuration value. The percentage withheld. |
Right sub-panel — totals (refreshes as you select rows or change the WHT Calculation):
| Field | Notes |
|---|---|
| Total Due | Sum of every selected line's outstanding fee. |
| Paying This time | The portion you are paying now. Equal to Total Due in the standard flow. |
| Withholding Tax | The tax that will be withheld. Zero in Exclude mode and zero in Depending On Payments mode when below cutoff. |
| Paying This time without WHT | Paying − WHT. The cash that will actually leave the drawer / be transferred to the recipient. |
The three calculation modes
1. Depending On Payments (commonly the default)
WHT applies only after the recipient's running total for this month at this institute crosses the configured cutoff. Below the cutoff, no WHT is deducted; once crossed, WHT is calculated on the current payment.
In formulas:
- If
Total Payment Completed for this monthis zero ⇒WHT = 0,Paying without WHT = Paying. - If
Total Payment Completed for this month≤ cutoff ⇒WHT = 0. - If
Total Payment Completed for this month> cutoff ⇒WHT = Paying × (Percentage / 100);Paying without WHT = Paying − WHT.
The cutoff is checked against the already-completed monthly total, not the running total after this payment. This means crossing the cutoff with the very payment you are about to make does not retroactively trigger WHT on this payment. WHT begins from the next payment after the cutoff is crossed.
2. Include Withholding Tax
WHT applies to every payment, regardless of the monthly total.
WHT = Paying × (Percentage / 100)Paying without WHT = Paying − WHT
Use this mode when the recipient is a senior consultant whose payments are always over the cutoff, or when policy requires WHT to be charged on every line.
3. Exclude Withholding Tax
WHT is set to zero regardless of any threshold.
WHT = 0Paying without WHT = Paying
Use this mode when WHT does not apply (e.g., for payments to staff who are below WHT-eligibility thresholds set elsewhere, or for ad-hoc reimbursements that should not be taxed). Each hospital decides its own policy.
Worked examples
The examples below assume the configuration values:
- Withholding Cutoff = LKR 100 000
- Withholding Percentage = 5 %
| Scenario | Mode | Already paid this month | Paying this time | WHT | Net paid |
|---|---|---|---|---|---|
| Junior doctor, mid-month, first payment | Depending On Payments | 0 | 30 000 | 0 | 30 000 |
| Junior doctor, second payment that month | Depending On Payments | 30 000 | 50 000 | 0 (still under 100k) | 50 000 |
| Senior consultant, already over cutoff | Depending On Payments | 150 000 | 70 000 | 3 500 (5 % of 70 000) | 66 500 |
| Always-tax policy | Include Withholding Tax | n/a | 70 000 | 3 500 | 66 500 |
| Exempted payment | Exclude Withholding Tax | n/a | 70 000 | 0 | 70 000 |
What changes when you switch modes on screen
Selecting a different mode from the WHT Calculation dropdown immediately recalculates the right-hand totals via an AJAX call. No bill is committed until you click Settle Professional Payment, so you can switch modes freely and see the effect on Withholding Tax and Paying This Time without WHT.
What happens at Settle
When you click Settle Professional Payment and confirm:
- The system creates the payment bill.
- The WHT amount is stored against the bill record (
bill.tax). - The recipient is paid the Paying This time without WHT amount through the chosen payment method.
- The WHT amount is retained — it appears on the WHT Report and on the financial WHT report for downstream filing.
The voucher printed for the recipient shows the gross, WHT, and net amounts in line with the on-screen totals.
WHT Report
A dedicated WHT report aggregates the withheld amounts across professional payments for tax filing.
Path: /reports/financialReports/wht.xhtml.
The report supports:
- Date range filter (From / To).
- Per-recipient breakdown (filter by professional).
- Optional payment-method filter.
- Export to Excel and PDF for filing with the revenue authority.
The body of the report shows each payment bill with its gross amount, withheld amount, and resulting net. Individual receipt detail is provided in a separate sub-grid in the same report (Individual Receipts Wise WHT Report).
Limitations and gotchas
- Per-institute monthly total. Depending On Payments uses the running total for the current institute only. A doctor who works at two institutes will see two independent thresholds. If your hospital chain wants a single global threshold across institutes, that is not the current behaviour — use Include Withholding Tax instead.
- Per-payment cutoff check. The cutoff is checked at the moment you open the payment screen. Two cashiers settling for the same doctor at the same time may both observe "below cutoff" and the second one's payment may go through without WHT even if it would have crossed the line.
- Calendar month boundary. The "this month" total resets at the first of the month. A payment near month-end can drag a partial month over the cutoff while the next month starts fresh.
- Refunded payments. Cancelling or refunding a settled professional payment bill reduces the running total. If a cancellation crosses you back below the cutoff, the next payment will see "below cutoff" again until the total climbs back over.
- Switching modes is permitted but logged via the bill. The mode chosen at settle is captured implicitly on the bill (through the withheld amount). There is no separate audit field naming the mode.