Skip to main content

​
Overview

  • Employee payroll taxes are applied at three levels: federal, state, and municipal.
  • This guide explains how to add employee tax information to ensure accurate payroll withholding and reporting.

​
🔹 Federal W-4

Use the addW4Information API to capture all federal withholding details required for payroll processing.

​
🔹 State W-4

State W-4 imports are more complex because field requirements vary by state. Follow these steps to add an employee’s state tax information:
  1. Use the getStateW4FormFields endpoint to retrieve the state-specific form fields required for the employee.
  2. Submit the employee’s state tax details using the addStateW4Information API. A sample request is shown below:
{
  "method": "addStateW4Information",
  "employeeId": "A31A0E84-3643-405A-B0E4-D229D0A194FB",
  "stateW4Information": {
    "Filing Status": "Married",
    "Withholding Allowance": "10",
    "Additional Withholding": "10.10",
    "NYC Withholding Allowance": "20",
    "NYC Additional Withholding": "14.00"
  }
}
In this example, NYC Withholding Allowance and NYC Additional Withholding are required because the employee is located in New York.

​
🔹 Miscellaneous State Taxes

Miscellaneous state taxes apply only in certain cases and are configured per employee. Rollfi currently supports Washington L&I taxes through this flow. Follow the steps below to add them:
  1. Retrieve the required fields for miscellaneous state tax setup using
    getEmployeeMiscellaneousStateTaxFormFields.
  2. Add the employee’s miscellaneous state tax information during onboarding using
    addEmployeeMiscellaneousStateTax.
    This ensures the tax is available for payroll processing.     
{
  "method": "addEmployeeMiscellaneousStateTax",
  "companyId": "7440E812-C699-4A94-AE14-A4B788D83299",
  "userId": "98CCB6CF-08DD-4C17-A367-B339CD5526CD",
  "employeeMiscellaneousStateTax": {
    "CompositeRate": "5",
    "RiskClassName": "Painter",
    "RiskClassCode": "121212",
    "PayrollDeductionRate": "4"
  }
}
To verify the miscellaneous state taxes were added correctly, or to view miscellaneous state tax that have already been added, use the getUser API.
  1. When preparing payroll, retrieve the employee’s miscellaneous state tax data using
    getEmployeeMiscellaneousStateTaxforPayroll.
    The response will resemble the following:
{
  "miscellaneousStateTaxes": [
    {
      "stateCode": "WA",
      "taxName": "Washington L&I",
      "taxDetails": [
        {
          "riskClassName": "Electrician",
          "noOfHours": 0
        }
      ]
    }
  ]
}
  1. Add the taxes to payroll using
    importRegularPayrollData
    or importRegularDifferentialPayrollData if the employee has differential pay.
    Include the miscellaneous state tax details returned in the previous step.
Note: You must update the noOfHours value when importing payroll data so miscellaneous state taxes can be calculated correctly. For the Washington L&I example above, this represents the number of hours the employee worked in the specified risk class.