A payroll file is “successful” when Workday finishes the pay calculation or delivers the extract. The withholding can still be wrong. The rules below are the ones Workday documents for U.S. income withholding orders and for the data a third-party payroll extract is supposed to carry. Vendor-specific tax APIs are not in those pages, so they are not in this guide.
What Workday Payroll will deduct even when the run looks normal
Setup Considerations: Income Withholding Orders (USA) says Workday processes creditor garnishments, federal administrative wage garnishments, federal student loans, federal tax levies, state tax levies, and support orders including lump sums. Once you record the order, deductions start during payroll processing. Workday determines the amount from disposable earnings, applies limits and priority, and can aggregate orders so a type does not exceed its limit. Workers cannot view their income withholding orders. You cannot delete an order Workday is calculating as part of a payroll, even when that calculation is unfinished. You inactivate it instead.
Record a Creditor Garnishment Withholding Order (USA) is where the “completed, and still wrong” cases are explicit:
| What you entered | What Workday does | Why a finished pay period is not proof |
|---|---|---|
| What you enteredBegin Date in the middle of the pay period | What Workday doesThe deduction starts in the pay period that includes that date, and Workday deducts the full pay period amount. | Why a finished pay period is not proofA mid-period order does not prorate itself. The full period amount is withheld if state law, which you are told to follow for the date, still produces that result in Workday’s calculation. |
| What you enteredEnd Date on a federal or state tax levy | What Workday doesEnd Date does not apply to federal tax levies. Workday does not stop a federal or state tax levy until you edit the order and select Inactive Order, after the release from the tax authority. | Why a finished pay period is not proofA release that never becomes the Inactive Order check box keeps withholding. The pay run completes either way. |
| What you enteredEnd Date on other orders | What Workday doesThe final amount, including fees, is deducted in the pay period before the one that contains the End Date. Processing also stops when the order is terminated, marked inactive, or repaid. | Why a finished pay period is not proofAn End Date in the next period still withholds in this one. |
| What you enteredPay period frequency that differs from the worker’s pay frequency | What Workday doesWorkday annualizes the order’s amount and de-annualizes it onto the worker’s frequency. The documented example is 200 USD monthly for a weekly-paid worker: 200 × 12 = 2,400, then 2,400 / 52 = 46.15 USD per week. | Why a finished pay period is not proofA file that expected the monthly figure, or a flat 200, will not match the calculated deduction. |
| What you enteredTotal debt left blank on an order type that requires it | What Workday doesCreditor garnishments, federal administrative wage assignments, federal and state tax levies, student loans, and wage assignments require a total. If the order states no total, Workday’s instruction is to enter 999,999.00. A bankruptcy order with no total continues until the End Date or until it is inactive. | Why a finished pay period is not proofThe sentinel total is not the worker’s balance. Reporting it outward as the debt is a bad file. |
| What you enteredMonthly limit | What Workday doesSupported for allocations and order amounts except federal and state tax levies. If an earlier pay period in the month was short, Workday can take more later in the month, up to the limit. | Why a finished pay period is not proofA “this period only” comparison looks like an over-withhold. |
| What you enteredCompany on the Date Received | What Workday doesThe company shown is the employee’s company as of Date Received. You pick the company for a future hire, for positions in more than one company, or after termination. You cannot change it after completed withholding-order pay results. | Why a finished pay period is not proofAn order recorded against the wrong company stays there once results exist. |
| What you enteredCase Number | What Workday doesUnique for the company, order date, order type, and worker. You cannot change it after the order has pay results. | Why a finished pay period is not proofA second order that reuses the case number will not save as a quiet correction. |
| What you enteredInternational assignment position in the United States | What Workday doesThe setup page says Workday does not support income withholding orders for workers who have an international assignment position in the U.S. | Why a finished pay period is not proofThose workers are outside this calculation. A “successful” U.S. payroll file that assumes every U.S. worker was evaluated for IWOs is overstating the run. |
Priority is assigned from agency rules. You can override it. Several orders whose amounts exceed the limit are reduced by those statutory rules, which you can inspect with All Payroll Withholding Order Data and View Payroll Withholding Order Data. Withholding Order Payments and Pay Calculation Results - Deduction Register are the reports for what was actually deducted in a period. A pay run with no error is not a substitute for the deduction register.
Support orders can carry a past-due amount. Workday limits the deduction to the maximum available. Lump-sum support orders respect Process in Regular Pay Period: selected means regular runs only, cleared means nonregular runs such as bonus runs. A bonus-only order that was flagged the other way will be absent from the bonus file and present on the regular file, and both files can complete.
Fees have a separate begin date. Workday maintains tax-authority employer fee limits and does not maintain agency fee limits. It warns when a fee exceeds a state monthly limit and does not, by itself, enforce the Fee Amount you typed. Allow Partial Fees on Edit Tenant Setup - Payroll is how a fee that would blow the maximum gets cut back. California creditor garnishments can use a local minimum wage override. The web services named for that rate are Get Withholding Order Local Minimum Wage Rate and Put Withholding Order Local Minimum Wage Rate.
Getting orders in and out
The setup page names the web services for a custom integration. It does not publish their request schemas on that page, so this guide does not invent fields:
- Put Deduction Recipients and Get Deduction Recipients move deduction-recipient information.
- Put Payroll Involuntary Withholding Order and Get Payroll Involuntary Withholding Orders move orders and can override the default rule Workday assigned.
- Electronic Income Withholding Order Inbound imports eIWO files as XML and as image-ready PDFs.
- Electronic Income Withholding Order Outbound generates acknowledgment records and sends them to the OCSE portal.
Create Deduction Recipient repeats Put Deduction Recipients for custom garnishment integrations and points Enable Payroll Third-Party Payments at settlement for involuntary withholding orders and court orders. For Workday Payroll for Australia, Workday does not settle during the pay run. You create a settlement run for third-party payments. A completed Australian pay calculation is not a completed payment to the recipient.
Copy Withholding Orders for Worker and Copy Withholding Orders for Workers exist for a company transfer. Until that copy happens, the new company does not have the order.
Third-party payroll: the extract can be perfect and the vendor still short
Overview of Third-Party Payroll lists Withholding Orders and Payroll Tax Withholding Elections among the categories a vendor must receive. The vendor takes the action. PECI transmits each change with its effective date and entry date, and it can include a priorValue when a field changes. PI sends the net change only. A delivered XML or CSV file is a successful integration. It is the vendor’s calculation that becomes the paycheck.
Two PECI limits matter here, from Creating PECI Integrations. The extract does not include contingent workers. It also omits one-time payments older than two years. If a garnishment or a tax adjustment depended on either of those, the vendor never saw it, and the integration can still complete. Payroll Vendor does not change the XML, so a label of “the right vendor” does not mean the order identifier was mapped. Field overrides are the mapping, and they belong in a report test before the nightly run. The night-before detection rules are in what breaks the file.
External payroll results can come back into Workday for reporting. That inbound result is not proof the withholding order was applied. It is proof the vendor sent a result.
Where Roots fits
Kiweely Roots (coming next) puts payroll, benefits, and tax in the set of fixes that are proven on Sandbox with the failed rows and then wait for approval. A withholding-order mapping change is in that set. Directory feeds are the ones that can be fixed, tested, and turned back on with a note to the owner. Register interest on the Roots page. Roots does not calculate a state’s disposable-earnings limit, and it does not replace the Inactive Order step on a levy.
What to open when net pay is wrong and the run is green
The levy kept coming out after the release.
Edit the order and select Inactive Order. End Date does not stop a federal tax levy, and it does not stop a state tax levy either. The setup page tells you to terminate orders for terminated employees after the final check, which is a separate step from the release.
The first deduction was a full period and the order arrived mid-period.
That matches the Begin Date rule. Confirm the begin date against the employee’s principal place of employment, which is the date instruction Workday gives, and read the deduction register before you change the map.
The vendor says they never got the order.
Confirm the category is in the PECI or PI output, that the worker is an employee rather than a contingent worker, and that the change was entered in time for the detection method on that launch. Then prove the corrected rows on Sandbox before you approve another production file. The approval pattern is prove the mapping on Sandbox.