Withholding

Withholding is the income tax you take out of an employee’s pay and send to the government for them. In the US there can be three layers:

Federal income tax, worked out from the employee’s Form W-4.
State income tax, for the state the employee works in (most states have one; some, such as Texas and Florida, do not).
Local income tax, charged by some cities, counties and school districts.

Social Security and Medicare are also taken from pay, but they are fixed percentages that need nothing from you, so this page is about income tax.

Before you start

The employee exists and has a Work state and a home address State on their record. See Employees.
You have the employee’s signed Form W-4, and their state withholding form if their state has one.
Your role can manage compensation (by default Super admin, Admin and CFO). Without it, these sections are read-only.

Federal withholding: the W-4

The W-4 is the form each employee fills in to tell you how much federal income tax to withhold. Bokapsys uses the figures from it with the IRS’s own method (the percentage method in IRS Publication 15-T) on every pay run.

Entering it yourself

Open Payroll → People → Employees and click the employee’s Employee #.
Scroll to Federal tax withholding (Form W-4). (It appears only after the employee has been saved once.)
Copy the figures from the form into the fields below.
Click Save at the bottom right. The message reads Saved, with W-4 in the list of what was updated.

Field	Where it is on the W-4	What to type	Example
Filing status (Step 1c)	Step 1(c)	The box the employee ticked.	Married filing jointly
Multiple jobs (Step 2c) → Box in Step 2c is ticked	Step 2(c) checkbox	Tick if they ticked it.	Unticked
Dependents credit (Step 3, USD a year)	Step 3 total	The dollar amount on the form, not the number of children.	4400
Other income (Step 4a, USD a year)	Step 4(a)	Yearly amount, in dollars.	1200
Deductions (Step 4b, USD a year)	Step 4(b)	Yearly amount, in dollars.	0
Extra withholding (Step 4c, USD each pay)	Step 4(c)	The extra amount per pay period, in dollars.	20
Exempt → No federal income tax withheld	Written “Exempt” below Step 4(c)	Tick only if they claimed exemption.	Unticked

If you never fill this in, Bokapsys withholds as for Single or married filing separately with no adjustments. A change applies from today; pay runs dated earlier keep the W-4 that was in force for them.

When the employee updates it themselves

Employees who use Bokapsys can sign their own W-4 under Account → My W-4 (see Employee self-service). That page follows the 2026 IRS form step by step, including dependents, other income, deductions, extra withholding and exemption, and asks them to sign it. Their signed W-4 replaces the one on their record from their next payroll, and you see it in the same Federal tax withholding (Form W-4) section.

Bonuses and back pay: the supplemental flat rate

A bonus paid separately from regular wages is a supplemental wage. The IRS lets employers withhold a flat percentage on it instead of using the W-4 tables.

On a Bonus or Back pay run, everything paid is supplemental. Bokapsys withholds federal income tax at a flat 22% (the 2026 figure in the app), plus any extra withholding from Step 4(c).
On an Off-cycle, Correction or Final pay run, earnings whose name says bonus, commission, severance, award, prize, incentive or back pay are withheld at the flat 22%; anything else uses the normal W-4 method.
An employee who claimed exemption is still exempt.

State income tax on a bonus is worked out with the state’s regular tables. The pay run warns you about this, because some states set their own flat supplemental rate; check it and enter a figure for the employee if it differs. See Run payroll.

State withholding

States Bokapsys holds tables for

For most states with an income tax, Bokapsys holds the state’s own published withholding tables or rate and uses them automatically for the employee’s state. It uses the filing status from the employee’s federal W-4 unless you enter the state certificate’s own details.

If the employee filled in a state withholding certificate (for example with allowances or a different filing status), enter it:

Open the employee’s record and scroll to State and local tax withholding.
Click Add a state figure. A window titled State withholding opens.
In Where it applies, choose the state.
Leave How it is worked out on Use the state’s tables.
Fill in what the certificate says (see the table below). You need at least the filing status, or one of the other details.
Click Save. You see Saved: “It applies from 1 January, so the next pay run uses it.”

Field	What it means	Example
Filing status	Single, Married filing jointly, Married filing separately or Head of household, as on the state certificate. Leave blank to use the same status as the federal W-4.	Married filing jointly
Allowances	The number of allowances or exemptions claimed on the state certificate.	2
Exemption amount ($ a year)	Only for states whose certificate asks for a dollar amount, such as Mississippi.	6000
Exempt → The employee claimed exemption from state withholding	Tick only if they claimed exemption on the state form.	Unticked
Extra each pay ($)	Only if the employee asked for more to be taken off each pay.	10.00

Some states’ figures are marked as not yet checked against the state’s own current publication. For an employee in one of those states, each pay run shows the warning “The [state] figures Bokapsys holds have not been checked against the state’s own current publication, so the amount withheld may be out of date.” Compare the amount with your state’s tables, and enter a figure for the employee if it differs.

States Bokapsys does not hold tables for

For a few states, Bokapsys does not hold published withholding tables, so it withholds nothing for them rather than guessing. In the app today these are Alabama, Arkansas, Delaware, the District of Columbia, Maine, New Mexico, North Dakota, Rhode Island and West Virginia. State coverage keeps the current list and the reasons.

For an employee in one of these states:

Their record shows an amber note in State and local tax withholding: Nothing is withheld for [state] income tax yet, with an Enter a figure button.
The Payroll Dashboard names the state in State income tax is not worked out for.
Each pay run lists them in the amber card Some tax could not be worked out, saying no state income tax was calculated.

The fix is to work out the figure from your state’s own tables and enter it for that employee, as described next. Once a figure is entered, the warnings stop and the figure is withheld every pay.

Enter a state figure for an employee

You can enter a figure for any state, whether or not Bokapsys holds its tables. A figure you enter replaces Bokapsys’s own calculation for that state.

Open the employee’s record and scroll to State and local tax withholding.
Click Add a state figure (or Enter a figure on the amber note). The State withholding window opens.
In Where it applies, choose the state.
In How it is worked out, choose A fixed amount each pay or A percentage of pay.
Fill in the fields below.
Click Save. You see Saved: “It applies from 1 January, so the next pay run uses it.” The figure appears in the table with the date it applies From.

Field	What it means	Example
Where it applies	The state this figure is for.	West Virginia
How it is worked out	A fixed dollar amount every pay period, or a percentage of the employee’s taxable pay.	A fixed amount each pay
Amount each pay ($)	The amount to withhold every pay period, in dollars. The state’s tables give you this for the employee’s pay and allowances.	42.50
Percentage of pay	The percentage to withhold. Type 2.5 for 2.5%.	2.5
Extra each pay ($)	Only if the employee asked for more to be taken off. Added on top. Leave blank otherwise.	10.00

A figure applies from 1 January of the current year, even if you enter it later. That way, if you recalculate a pay run from earlier in the year, it is worked out correctly too.

If the employee’s pay changes, a fixed amount does not change with it. Work out the new figure from the state’s tables and update it.

To change a figure, click the edit icon on its row, change the values and click Save. To stop using it, click the red bin icon and confirm Remove. Pay runs from today no longer use it; pay runs already made keep what they used.

You cannot enter a figure for federal withholding here. Federal withholding always comes from the W-4. Use Extra withholding (Step 4c) on the W-4 for extra federal tax.

Local taxes

Some cities, counties and school districts charge their own income tax, usually a flat percentage of pay. Bokapsys does not hold local tax rates, because there are thousands of them and they change often.

The Where it applies list offers states only today; no cities, counties or school districts are listed. Until they are, Bokapsys cannot withhold local income tax through payroll. Handle it outside Bokapsys and ask your accountant how to record it. See State coverage.

Reciprocity: living in one state, working in another

Normally you withhold income tax for the state where the employee works. Some neighbouring states have reciprocity agreements: if an employee lives in one and works in the other, they can ask you to withhold for their home state instead, by giving you an exemption certificate.

Bokapsys knows the 2026 agreements and compares each employee’s Work state with the State in their home address.

With a certificate on file, Bokapsys withholds for the home state. To record the certificate, open the employee’s record, tick Certificate on file under State tax reciprocity in the Employment section, enter the Certificate received date and click Save.
Without a certificate on file, Bokapsys withholds for the work state and the pay run warns: “[Home state] and [work state] have a reciprocity agreement, but this employee has no exemption certificate on file, so tax was withheld for [work state] where they work. Record the certificate to withhold for their home state instead.”

State unemployment tax always follows the work state, whatever the reciprocity situation. Reciprocity is only about income tax.

State disability and paid family leave

California, New York, New Jersey, Rhode Island, Hawaii, Washington, Massachusetts, Oregon, Colorado and Connecticut run state disability or paid family leave programs funded through payroll. Bokapsys does not hold their rates, so nothing is calculated for them, and a pay run for an employee who works in one of these states warns you. Work out the employee and employer amounts from the state’s current figures and add them as fixed pay items. See Compensation.

Worked example

Sam lives and works in Arkansas, earns $2,000 every two weeks, and his Arkansas form and the state’s tables give $58.40 per pay. Bokapsys does not hold Arkansas tables, so:

Open Sam’s record → State and local tax withholding → Enter a figure.
Where it applies: Arkansas. How it is worked out: A fixed amount each pay. Amount each pay ($): 58.40.
Save.

On his next pay run, $58.40 is withheld for Arkansas and the “no state income tax was calculated” warning no longer appears for him.

How to check it worked

Open a calculated pay run and click the employee’s name: Federal Withholding, State Withholding and Local Withholding show the amounts.
The amber card Some tax could not be worked out no longer lists the employee.
On the employee record, the State and local tax withholding table shows each entry, How it is worked out and its From date.

Common problems

Message or symptom	What it means and how to fix it
Choose where it applies	Pick a state in Where it applies before saving.
Enter at least the filing status from the state certificate	With Use the state’s tables, fill in at least one detail from the state form.
Enter the amount to withhold each pay, like 42.50	The fixed amount is empty or not a dollar amount.
No state tax on the payslip	The employee has no Work state, their state has no income tax, or it is one of the states without published tables and no figure has been entered.
Tax is withheld for the work state although the employee lives elsewhere	No reciprocity certificate is recorded. Tick Certificate on file if they gave you one.

Employees

State coverage

Run payroll

Employee self-service