Overview
If a payroll from your integrated payroll provider (Rippling, Paylocity, TriNet, or Gusto) is failing, rejected, or not processing correctly, use this guide to identify and resolve the issue.
**Time-sensitive**: Check the payroll effective date immediately. If it's approaching or has passed, contact Betterment support right away for priority assistance.
Step 1: Gather Key Details First
Before troubleshooting, collect the following information:
- Payroll provider name (Rippling, Paylocity, TriNet, or Gusto)
- Your company ID
- Payroll effective date
- Current payroll status shown in your Betterment admin portal (pending, failed, rejected, or canceled)
Step 2: Identify the Symptom
Review the symptom you're experiencing and follow the corresponding next step:
|
Symptom |
Likely Cause |
Next Step |
|
"Approved but not finalized yet" appears in your dashboard |
Payroll is still open in your payroll provider |
Go to Step 4 |
|
File rejected due to disallowed source |
A contribution source was removed from your plan but is still in the payroll file |
Go to Step 3 |
|
Some employees are missing from the file |
Employee ID or mapping mismatch between systems |
Go to Step 3 |
|
Employer match calculation is incorrect |
Mismatch in match formula setup (% of contribution vs. % of compensation) |
Go to Step 3 |
Step 3: Review Plan Configuration vs. File Contents
Compare your plan design in Betterment to what's coming through from your payroll provider. Check for the following:
- Contribution sources match — No removed sources are still present in the payroll file
- Safe harbor type is correct
- Match formula aligns — Confirm whether the match is based on % of compensation or % of contribution
- Effective dates are accurate
- Deduction codes in your payroll provider match what Betterment expects
What to Do Based on Your Findings
|
Finding |
Action |
|
Configuration mismatch found |
Update your plan configuration with Betterment support, OR work with your payroll provider to adjust deduction codes or contribution sources. Then resubmit the payroll. |
|
Missing employees or incorrect employee ID mapping |
Work with your payroll provider to correct employee ID mapping and rerun the payroll. |
|
No mismatch found |
Move to Step 4 to verify the payroll has been finalized in your provider system |
Step 4: Confirm Finalization Status with Your Payroll Provider
Many processing issues occur because Betterment attempts to pull a payroll that hasn't been finalized yet.
Check: Is the payroll fully finalized and closed in your payroll provider system?
Note: This is especially common with Rippling. Make sure the payroll run is fully approved and closed before expecting Betterment to process it.
What to Do Based on the Status
|
Scenario |
Action |
|
Payroll not yet finalized in the provider |
Wait until you finalize the payroll in your provider system, then check Betterment again |
|
Payroll was corrected or rerun in the provider |
Confirm your provider generated a new file. Contact Betterment support to verify the updated file has been retrieved. |
|
Payroll is finalized but still failing |
Configuration and provider setup are not the issue — proceed to Step 5 to contact support |
Step 5: If needed, contact Betterment Support
If the payroll is finalized in your provider, your plan configuration is correct, and the file is still failing to process, please contact Betterment support with the following information:
|
Information Needed |
Your Details |
|
Company ID |
|
|
Payroll ID (if available) |
|
|
Payroll provider name |
|
|
Full error message text |
|
|
Names of affected employees (1-2 examples) |
|
|
Steps you've already completed |
Providing this information upfront will help our team resolve the issue more quickly.