-
Notifications
You must be signed in to change notification settings - Fork 137
Admin Withholding Tax Configuration
Withholding Tax (WHT) on professional payments is governed by a handful of configuration keys read by StaffPaymentBillController whenever a payment screen opens. This article lists every key, explains how they interact, and gives recommendations for typical institutions.
For the end-user view of WHT (how the panel looks on the bill screen, what the three modes do at the cashier's level), see Withholding Tax on Professional Payments.
All keys are stored in the ConfigOption table and edited through the in-app configuration screen (typically reached via Administration → Application Configuration or an equivalent menu). They are global by default — every institution sees the same value — unless your installation has been customised for per-institution scope.
| Key | Type | Default | Purpose |
|---|---|---|---|
Withholding Tax Limit |
Number | 100 000 if blank or 0 | The monthly cumulative payment threshold above which WHT applies under the Depending On Payments mode. The value defaults to 100 000 only when blank or zero — set it explicitly to anything else (including a number less than 100 000). |
Withholding Tax Percentage |
Number | 0 if blank | The percentage withheld. Stored as a number, applied as paying × (pct / 100). |
| Key | Type | Default | Purpose |
|---|---|---|---|
Allow User To Select Whether To Pay Withholding Tax During Professional Payments |
Boolean | true | When true, the WHT Calculation dropdown is editable by the cashier on the payment screen — the cashier can pick Depending On Payments, Include, or Exclude. When false, the dropdown is replaced with a fixed badge displaying whichever mode the boolean switches below dictate; cashiers cannot change it. |
The mode is not stored as a single field. It is derived from three booleans evaluated in this order:
| Key | If true → Mode shown |
|---|---|
Withholding Tax Calculated Depending On This Month's Payments During Professional Payments |
"Depending On Payments" |
Withholding Tax Is Always Calculated During Professional Payments |
"Include Withholding Tax" |
Withholding Tax Is Never Calculated During Professional Payments |
"Exclude Withholding Tax" |
If none is true, the system defaults to Depending On Payments.
Setting more than one of these three to true is supported by the data store but creates ambiguity: only the first match in the order above is used. The recommended practice is to set exactly one boolean to true and the other two to false, so the active mode is unambiguous from the configuration.
WHT applies above LKR 100 000 per month per professional, at 5 %, and cashiers can override per-payment.
| Key | Value |
|---|---|
Withholding Tax Limit |
100000 |
Withholding Tax Percentage |
5 |
Allow User To Select Whether To Pay Withholding Tax During Professional Payments |
true |
Withholding Tax Calculated Depending On This Month's Payments During Professional Payments |
true |
Withholding Tax Is Always Calculated During Professional Payments |
false |
Withholding Tax Is Never Calculated During Professional Payments |
false |
Every professional payment is taxed, no override allowed.
| Key | Value |
|---|---|
Withholding Tax Limit |
(ignored) |
Withholding Tax Percentage |
5 |
Allow User To Select Whether To Pay Withholding Tax During Professional Payments |
false |
Withholding Tax Is Always Calculated During Professional Payments |
true |
Withholding Tax Calculated Depending On This Month's Payments… |
false |
Withholding Tax Is Never Calculated During Professional Payments |
false |
Never deduct WHT inside HMIS; the finance team handles it externally.
| Key | Value |
|---|---|
Withholding Tax Percentage |
0 |
Allow User To Select Whether To Pay Withholding Tax During Professional Payments |
false |
Withholding Tax Is Never Calculated During Professional Payments |
true |
| Others | false |
- Per-doctor exemption. There is no per-practitioner WHT override. If one consultant is exempt while others are not, set the mode to Allow user override (true), and ask the cashier to pick Exclude on that consultant's payment.
-
Reporting filter. The WHT report at
/reports/financialReports/wht.xhtmlis not driven by these keys; it always reports actual withheld amounts regardless of mode. - Cross-institute totals. The Depending On Payments threshold uses per-institute running totals (see Withholding Tax on Professional Payments for the limitation). The keys do not change this.
- Year-to-date thresholds. The threshold resets at the start of each calendar month, not at the start of a tax year. There is no annual cap setting.
| Task | Steps |
|---|---|
| Change the WHT percentage mid-year | Edit Withholding Tax Percentage. New value applies to every payment from now on. Past bills are not retroactively recalculated. |
| Switch from "Depending On Payments" to "Always" | Set the Always boolean true and the Depending On Payments boolean false. Optionally also turn off the user override switch. |
| Disable WHT entirely | Set the Never boolean true. The system still shows the WHT column in totals, but the value is zero. |
| Re-enable WHT after a holiday period | Set the Depending On Payments (or Always) boolean true again, and the Never boolean false. Past payments made while WHT was off remain unchanged. |
| Audit current setting | Open the configuration screen and read the four keys; the active mode is whichever boolean is the first true in the precedence order above. |
- The configuration model uses three booleans where a single enum would be clearer. The chance of misconfiguration (two booleans both true, none true, etc.) is real; double-check after each change.
- No effective-dated setting. Changes apply immediately and irrevocably to subsequent payments.
- No segregation of duties around the keys themselves — anyone with
AdminConfigor equivalent can edit them.