# 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](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](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. ## Related articles - [Withholding Tax on Professional Payments](Withholding-Tax-on-Professional-Payments) — end-user side - [OPD Doctor Payments — All Due](OPD-Doctor-Payments-All-Due) - [Inward Professional and Surgery Payments](Inward-Professional-and-Surgery-Payments) - [Admin — OPD Doctor Payment Behaviour](Admin-OPD-Doctor-Payment-Behaviour) [Back to Admin — Practitioner Module Configuration Overview](Admin-Practitioner-Module-Configuration-Overview)