W-2 payroll
Pay W-2 employees from the same Wingspan account you use for contractors: set up worksites and Employee engagements, assign employees to them, and run payroll with the V3 API.
Wingspan runs W-2 payroll on the same account, payees, and engagements you already use for contractors. An employee is a Payee with context: Employee, assigned to an Employee engagement at one of your worksites. Each pay period, Wingspan turns the hours you approve into pay statements, works out federal, state, and local withholding and your employer taxes, and pays the run on your schedule. This page explains how the pieces fit together and the order to set them up.
Important: W-2 payroll is an add-on module. Your Wingspan team turns it on for your account and sets up each state where you're registered as an employer. Until it's on, W-2 calls for your account don't succeed. To check, call
GET /v3/payments/employer-payroll-profiles: an account with W-2 payroll returns one profile.
How employees differ from contractors
| Contractor | Employee | |
|---|---|---|
Payee context | Contractor | Employee |
| Engagement type | Contractor | Employee, at a worksite or remote |
| What they're paid from | Payables | Approved work logs, which become pay statements |
Payroll run type | Contractor | Employee, one on-cycle run per pay period |
| Taxes | None withheld | Federal, state, and local withholding, plus your employer taxes |
| Tax forms they complete | W-9 | Form W-4 and the state withholding certificate for their state |
| Year-end form | 1099-NEC | W-2 |
A payee's context decides which engagement types they can hold. You can't put a Contractor payee on an Employee engagement, or the other way around.
The objects
| Object | What it is |
|---|---|
EmployerPayrollProfile | Your account's W-2 employer setup: the states you're registered in and how your payroll taxes are filed. Wingspan creates it when W-2 payroll is turned on. You can read it but not change it. |
Worksite | A physical place your employees work. Its state decides which state taxes apply. |
Engagement with engagementType: Employee | A template for a W-2 role, such as "Field representative, Los Angeles". It carries the rate card, the work definition, and the Employee tax forms requirement. |
Payee with context: Employee | Your record of one employee. |
PayeeEngagement | One employee assigned to one Employee engagement, with a worksite, start date, and job title. |
| Tax elections | The employee's Form W-4 elections and state withholding certificate for your employer relationship, read and updated through their assignment. |
PayPeriod and PayrollRun | Your employee pay schedule creates a pay period and an on-cycle payroll run for it. |
WorkLog | The hours an employee worked in a pay period. |
PayStatement | One employee's earnings, withholding, and net pay in one run. Approving a work log creates it. |
flowchart LR A[Employer payroll profile<br/>turned on by Wingspan] --> B[Worksite] B --> C[Employee engagement] D[Payee<br/>context Employee] --> E[PayeeEngagement<br/>worksite, start date, job title] C --> E E --> F[Work log<br/>hours for a pay period] F -->|approve| G[Pay statement<br/>gross to net] G --> H[Employee payroll run<br/>paid on the pay date]
What Wingspan does and what you do
Wingspan calculates gross-to-net for every pay statement, including federal income tax, Social Security, Medicare, state and local withholding, and your employer taxes. It debits your payroll funding source, pays employees on the pay date, deposits the taxes, files your payroll tax returns, and issues W-2s at year end.
You set up worksites and Employee engagements, assign employees, approve their hours before each run's approval deadline, and keep each employee's tax elections current. Whether a worker is an employee or a contractor is your decision. This isn't legal or tax advice. Consult a qualified professional about your obligations.
Read the pages in this order
- Set up W-2 payroll: confirm W-2 payroll is on, add worksites, check your employee pay schedule and funding, and create Employee engagements.
- Add and assign employees: create an employee, link their Wingspan account, assign them to an Employee engagement, and track what they still need to complete.
- Pay employees: log and approve hours, follow an Employee payroll run from draft to paid, and run an off-cycle payroll.
- Pay statements: read a pay statement, preview gross-to-net before a run closes, and cancel a statement.
For a working walkthrough, see Hire and assign a W-2 employee.
Related pages
Updated 13 days ago