Skip to main content
Withholding tax is tax you deduct from a payment to a supplier and remit to the tax authority on their behalf, instead of paying the full amount to the supplier. For example, on a 1,000,000 service bill subject to 6% WHT, you pay the supplier 940,000 and hold back 60,000 to remit to the authority. Hitaji’s withholding codes let you configure these rules once — the rate, the bracket thresholds, and the GL accounts — so the system computes and posts the withheld amount for you at bill or payment time. You’ll find this at: /settings/erp/finance/withholding-codes — in the left navigation under Settings → ERP / Finance → Withholding Codes. (The older link /accounting/settings/withholding-codes redirects here.)
📷 Screenshot: Withholding Codes settings page listing each code with its basis and thresholds — to be added.

​
Multi-business note

Withholding codes are stored per business. Each business configures its own codes and keeps its own running totals. Switch the active business with the business switcher before adding or editing codes.

​
How a withholding code works

A withholding code bundles together everything needed to apply WHT to a vendor payment:
  • A basis — whether the rate is applied to the gross amount (before VAT) or the net amount (after VAT). Uganda typically withholds on net; some cases use gross.
  • One or more thresholds (a bracket table) — the rate to apply, and the cumulative amount at which it starts. The simplest code has a single threshold of 0, meaning WHT applies “from the first shilling”.
  • GL accounts — a payable account (the WHT you’ve withheld and now owe the authority) and an optional recoverable account (WHT that can be reclaimed).
  • Vendor categories — optional labels used to match the code to the right kind of supplier.

​
Thresholds explained

Thresholds let a single code change rate as a vendor’s cumulative year-to-date amount grows. Each threshold row has:
  • Threshold amount — the cumulative amount at or above which this row applies.
  • Rate percent — the WHT rate for that bracket.
  • Row order — the display/evaluation order.
The engine picks the applicable bracket based on the vendor’s year-to-date cumulative total (see “Balances” below). A code must have at least one threshold — Hitaji rejects a code with none.
The common Uganda setup: one threshold with threshold amount = 0 and your standard rate (e.g. 6%). That applies WHT to every payment regardless of cumulative total.

​
Creating a withholding code

  1. Go to Settings → ERP / Finance → Withholding Codes (/settings/erp/finance/withholding-codes).
  2. Click Add Withholding Code.
  3. Fill in the fields below, including at least one threshold row.
  4. Save.
📷 Screenshot: Create-withholding-code form with basis selector, account pickers, and the threshold rows table — to be added.

​
Fields

​
How WHT is applied and posted

When a withholding deduction is taken on a vendor payment, Hitaji records it as a deduction line on that payment. Each deduction line carries the withholding code, the amount withheld, and the GL account it hits. Behind the scenes. A withholding deduction reduces the net cash leaving on the payment and credits the WHT Payable account. So for a 1,000,000 payment with 60,000 WHT: the supplier receives 940,000 of cash, and 60,000 is parked in WHT Payable as money you now owe the tax authority. When you later remit to the authority, that payable is cleared.
A payment can carry several deduction lines (WHT, bank charges, early-payment discount, or other). Only the withholding lines require a withholding code; the engine also keeps a cached total of WHT withheld on the payment for reporting.
The exact moment WHT is computed — at bill submit or at payment — is governed by your business’s WHT timing setting.

​
Balances (year-to-date running totals)

To apply the correct bracket, Hitaji keeps a withholding balance per party, per code, per fiscal year. Each balance row tracks:
  • the cumulative amount transacted with that party this year, and
  • the cumulative tax withheld so far.
When a new deduction is calculated, the engine reads this running total to decide which threshold bracket applies, then updates the total within the same posting transaction (with a lock so concurrent payments can’t double-count). This is what makes graduated thresholds — “the first X is at one rate, amounts above X at another” — work correctly across many payments to the same vendor over a year. You don’t maintain these balances by hand; they are accumulated automatically as you post bills and payments.

​
Editing a withholding code

Open a code and change its label, basis, accounts, vendor categories, active flag, or its threshold rows. If you replace the thresholds, you must still provide at least one — Hitaji rejects an empty threshold set. Any payable/recoverable account must still be an active account in the current book.

​
Deleting a withholding code

A withholding code is soft-deleted. You cannot delete a code that is still referenced — if any bill line or any payment deduction uses it, Hitaji blocks the deletion with a count, e.g. “WithholdingCode WHT6 is referenced by 3 bill line(s) / payment(s) and cannot be deleted”. Deactivate the code instead so it leaves the pickers while preserving history and balances.

​
Access & permissions

  • Viewing withholding codes requires the accounting:read scope.
  • Creating, editing and deleting withholding codes requires accounting:admin or accounting:config.