Admin Withholding Tax Configuration - hmislk/hmis GitHub Wiki

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.

Where the keys live

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.

The complete key list

Numeric thresholds

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)`.

User-control switch

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.

Calculation mode switches (mutually exclusive)

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.

Worked configurations

Example 1 — Standard hospital (most common)

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

Example 2 — Hospital with policy "always tax"

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

Example 3 — Hospital that handles WHT manually outside HMIS

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

What the keys do not control

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.xhtml is 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.

Operational tasks

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.

Limitations

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 AdminConfig or equivalent can edit them.

Back to Admin — Practitioner Module Configuration Overview