Managing Validation Errors On Integrated Payroll Contributions – Vestwell Help Center

In this article, you will learn about a variety of validation errors that could occur on contributions that are submitted via an integration from your payroll company. Even when bypassing the portal for contribution submission via a payroll integration, employers are still responsible for managing validation errors that occur. Please read on to learn more about validation error handling and your responsibilities for remediating any errors. This article will review what happens when an error is detected in a contribution file and what steps the employer is responsible for remedying the issue.

If you have payroll contributions integrated through your payroll provider:

Viewing Contribution Validations in the portal

When you receive an email noting that one or more contributions experienced a validation error, go to the portal and select the impacted contribution from the history section of the "Contributions" dashboard. Click on the contribution date to see the contribution details.

Saver (Employee) and Contribution Validation Types that Result in Contribution Removal

Certain validation errors will result in the impacted contribution being removed from the submission so that the rest of the contributions can be processed in a timely manner. Each of these requires the employer to review and take action to remediate the issue or refund the deducted money to the employee.

Validation Description Validation Logic Systemic Action Taken Employer Remediation Options
Missing SSN The saver's SSN needs to be added to a contribution submission. Contribution record(s) without SSN are automatically removed from the contribution submission. Reason: "Missing a valid SSN.” If there was no contribution associated with the record, you may: - Ignore the error, or - Correct the missing SSN on your payroll system so that it can get properly processed next time. If there was a contribution associated with the record, you may: - Update this employee’s SSN and resubmit their contribution via an off-cycle submission tool found under the ‘Other Options’ menu on the Contributions landing page OR - Return the funds to the impacted employee if the contribution was deducted in error. No other action is necessary. In case of duplicate Social Security Number error, all the same records are dropped and should be reviewed, consolidated, corrected, and resubmitted, if appropriate.
Bad SSN format The saver's SSN is not properly formatted with nine digits. Failing record(s) are automatically removed from the contribution submission. Reason: “Improperly formatted SSN.”
Invalid SSN Invalid SSNs are identified as follows: 1) All the same digits (i.e. 111-11-1111) 2) Zeros (0) in positions 1-3 or 4-5 or 6-9 of the SSN. (i.e. 00-352-1234) 3) 123-45-6789 4) 987-65-4321 Failing record(s) are automatically removed from the contribution submission. Reason: “Invalid SSN.”
Duplicate SSN More than one record on submission with the same SSN. Contribution record(s) are automatically removed from the contribution submission. Reason: “Duplicate SSNs.”
Missing names First or last names are missing from the submission (SSN and names are always required). Contribution record(s) are automatically removed from the contribution submission. Reason: “Missing name.” If there was no contribution associated with the record, you may: - Ignore the error OR - Correct the missing name on your payroll system so it can be properly processed next time. If there was a contribution associated with the record, you may: - Update this employee’s Name and resubmit their contribution via an off-cycle submission tool found under the ‘Other Options’ menu on the Contributions landing page OR - Return the funds to the impacted employee if the contribution was deducted in error. No other action is necessary.
Unrecognized employee All required data about that saver must be included when adding a new employee, along with a contribution submission. In this validation, any employee who does not match an existing employee in the plan and who needs more personal data to be set up is identified. Contribution record(s) are automatically removed from the submission if insufficient data is available to add the unrecognized saver. Data is insufficient to add a new saver if: 1) Not all required fields are present with valid data. Required fields are SSN, First Name, Last Name, Date of Birth, Date of Hire, Address 1, City, State, and Zip. 2) Optional fields, if present, are properly formatted. If there was a contribution associated with the record, you may: - Manually resubmit the contribution for an enrolled employee via the off-cycle submission tool found under the "Other Options" menu on the "Contributions" page OR - Return the funds to the employee if the contribution was deducted in error. No other action is necessary OR - If this employee should be newly enrolled in the plan, add the person to the employee roster while manually resubmitting the contribution via the off-cycle submission tool under the "Other Options" menu on the "Contributions" page. If there is no contribution for the unrecognized employee, no action is required. However, if you expect to contribute for that employee in the future, then update the required information in your payroll system to avoid future validation errors.
Bad contribution format A saver has a contribution for less than $0, contains a non-number value, or the dollar amount has more than two decimal places. Poorly formatted records from contribution submissions are automatically reduced to $0. Non-number values get normalized into Null. Reason: “Invalid contribution amount” Values with more than two decimal places get rounded to 2 decimal places. If the negative or non-numeric contribution was submitted in error, then: - Manually resubmit the corrected contribution via the off-cycle submission tool found under the ‘Other Options’ menu on the Contributions landing page AND - Update your payroll system to avoid future problems. If the negative contribution was submitted as an offset to prior contributions, then: - Please note that you cannot correct a previously submitted contribution by sending in a negative contribution as an offset. Please contact your representative to reverse incorrect contributions.
Employer contributions not required for long-term part-time employees (LTPT) Employer contributions are rejected for any employee designated as long-term part-time (LTPT). Employer contributions are automatically removed from the submission. Employee contributions are not impacted. Employer contributions that are rejected will not be processed from your bank account. Therefore, no additional action is required from you.

Employee and Contribution Validation Types - Contribution is Processed

Some contribution validations identify incomplete or mismatched data that DON'T require the contribution to be removed. This occurs when we already have this information on file for the employee. In these cases, the employer should take action to ensure data is corrected in the payroll system to avoid future error notifications.

Validation Description Validation Logic Systemic Action Taken Employer Remediation Options
Wrong Date of Hire (DOH) format on an existing Employee - required field The date is not in a valid date format. DOH must be <= today's date & > DOB. The contribution record(s) has not been removed from the contribution submission. The latest date was pulled from the database. An error is displayed on the Contribution Detail screen. The employer must update the hire date in their payroll system to an acceptable date to avoid ongoing error notifications.
Bad Date of Rehire (DORH) format Bad Date of Termination (DOT) format - Optional fields The date is not in a valid date format. The contribution record(s) are not removed from the contribution submission—the latest date is pulled from the database. An error is displayed on the Contribution Detail screen. The employer must update the date of rehire or date of termination in their payroll system to an acceptable date to avoid ongoing error notifications.
Bad Zip and Bad State Zip or State fields are not properly formatted. Zip must be either 5 or 9 digits, with a dash. The contribution record(s) has not been removed from the contribution submission. The latest date was pulled from the database. Even if only one field is wrong, we pull the entire address from the database. An error is displayed on the Contribution Detail screen. The employer must update their payroll system's zip code or state to an acceptable format to avoid ongoing error notifications.
Unrealistic Date of Birth (DOB) DOB does not fall into 10 to 100 years old age range. The Contribution record(s) is not removed from the contribution submission, but the Date of Birth on the contribution is updated to the last known valid date of birth stored in the database. An error is displayed on the Contribution Detail screen. The employer must update their payroll system's date of birth record to an acceptable birthdate to avoid ongoing error notifications.
Bad Date of Birth (DOB) format DOB is not in a valid date format. The Contribution record(s) is not removed from the contribution submission, but the Date of Birth on the contribution is updated to the last known valid date of birth stored in the database. An error is displayed on the Contribution Detail screen. The employer must update their payroll system's date of birth record to an acceptable birthdate to avoid ongoing error notifications.