Payroll Connect FAQ
Answers to common setup, pay-document and troubleshooting questions about Payroll Connect.
For what the app is and how to set it up from scratch, see the
Payroll Connect Overview.
Setup
Do I need to set up a connection before anything in Payroll Connect works?
Yes. Employee sync, paycheck import, tax documents and timesheet submission all need an active connection to a payroll provider. Payroll Connect requires a licence and is off by default, so an administrator first enables it from Admin → Apps → All Apps. Then create a connection on the Connections tab and enter your provider credentials. A new connection starts as a Draft; clicking Test & activate makes it Connected once the test passes.
Which payroll providers can I connect to?
Payroll Connect has built-in connectors for ADP Workforce Now, Workday HCM, Gusto, BambooHR, Paychex and Infor CloudSuite HCM. A Custom Integration connector works with your own API base URL, authentication and endpoints. MangoPay is a demonstration provider with pre-filled settings, for evaluating the app.
Who can use the admin side of Payroll Connect?
Access comes in three tiers:
- A Contributor for Payroll Connect can view connections, sync logs, mappings and paychecks, run a sync, and submit approved timesheets.
- An App admin can also create and change connections, credentials, mappings and import settings, and open Salary Management and Compensation Changes.
- Only a company admin can delete a connection, approve an import request, change a salary, export the salary report, or approve or reject a compensation change.
Company admins hold all three tiers automatically. Everyone else sees only their own paychecks and tax documents.
Tax documents (W-2, 1099, 1095-C)
Where do I find my W-2 or 1099?
Open My Paychecks and select the Tax documents tab; on your phone, tap Tax documents in Payroll Connect. The tab lists your year-end forms by tax year. It appears only when your employer offers tax documents through MangoApps. If it is missing, ask HR or payroll for a copy.
Why do I have to verify it’s me before I can download my W-2?
Tax forms carry your full Social Security number, so every download asks you to confirm your identity first. You confirm with your password, or your personal PIN if you have set one. People who sign in through single sign-on confirm at their sign-in provider or with a one-time code. One confirmation covers tax-document downloads on the web and the phone for 15 minutes. Every download is recorded in the audit trail.
How do I let employees download their W-2 and 1099 forms?
Turn on the Tax documents switch for the payroll connection at Admin › Integrations. It is off until you turn it on. W-2 and 1099 forms are available from ADP, Gusto and Infor connections. Forms are fetched from the provider each time someone downloads one and are never stored in MangoApps. A Form 1095-C also appears on the same tab while Benefits Management is enabled.
Can I still get my W-2 after I leave the company?
Only if your former employer has turned it on in the Former Employee Portal. The portal is off by default. An admin enables it at People › Settings › Former employees, and it must also be switched on in the Portals app. Provider W-2 and 1099 forms need a separate switch in that section, Let former employees download W-2 and 1099 forms from your payroll provider, which is off by default. That switch also needs Payroll Connect enabled, pay amounts not hidden, and a connection with its Tax documents switch on. The portal signs people in with a code sent to their email or phone, and every download is recorded in the portal audit log.
Permissions and access
Can I hide pay amounts from employees entirely?
Yes. Turn on Hide Pay Amounts in Admin › General Settings (payroll settings). Employees then lose paycheck figures on My Paychecks, the phone paycheck screen and the paycheck dashboard widgets. W-2 and 1099 forms are hidden with them, because they are pay documents. A Form 1095-C carries no pay figures, so employees still see it. Company admins are exempt and keep seeing everything.
Why does viewing salary or paycheck data ask me to re-verify my identity?
Salary and pay figures are sensitive data. Salary Management, Compensation Changes and each connection’s Paychecks view ask for a recent identity confirmation (a “step-up”) before showing figures. A confirmation lasts 15 minutes and covers only the area you confirmed for. For example, confirming to read paychecks does not unlock tax-document downloads. Every reveal is recorded in the audit log.
Day-to-day
How are employees matched between MangoApps and the provider?
Each sync matches a provider record to a MangoApps user by email address first, then by employee ID where the provider supplies one. Gusto connections match on email alone. A connection’s Field Mappings decide which provider fields supply those values. You can also map someone by hand on the connection’s Employee Mappings page by entering their provider employee ID.
What happens when a sync finds an employee who isn’t in MangoApps?
By default nothing is created: the record is logged and skipped. Change this on the connection’s Import Settings page, under When an employee exists in payroll but not in MangoApps:
- Skip (the default) — log it, import nothing.
- Review required — queue it on the connection’s Import Requests page, where a company admin approves or rejects it.
- Auto-create — create the MangoApps user automatically, but only when Enable automatic user creation is also ticked.
How do I push approved timesheets to my payroll provider?
Open the Timesheet Submissions tab, choose the connection, and submit approved timesheets individually or in bulk. A single submission from the page handles up to 25 timesheets. For more, use Queue in background, which submits up to 200 per run. Timesheet submission is never automatic: scheduled syncs do not send timesheets. Sample-data timesheets are never offered.
How does compensation change approval work?
A compensation change (salary increase or decrease, bonus, promotion, demotion or adjustment) starts as Pending. A company admin approves or rejects it on the Compensation Changes tab. The person who requested a change cannot approve it themselves. Once approved, a daily job applies it on the effective date: it updates the employee’s pay, records the change in their compensation history, and notifies them. Approved changes update MangoApps only and are not sent to the provider, so record them in your payroll system as well.
Can I turn off one operation without deactivating the whole connection?
Yes. On the connection’s edit page, under What this connection may do, turn off Submit approved timesheets to the provider or Retrieve paychecks from the provider. The connection then refuses that operation, for scheduled and manual runs alike, while everything else keeps running.
When something looks wrong
“My pay stub isn’t showing up”
Paychecks come from the connected provider, not from MangoApps. Check three things:
- The connection is active and has synced recently (the Connections tab shows the last sync).
- The employee is mapped to their provider record on the connection’s Employee Mappings page.
- Retrieve paychecks from the provider is on for that connection.
BambooHR has no paycheck API, so paychecks cannot be imported from a BambooHR connection.
Gusto takes no timesheets from Payroll Connect: there is no verified Gusto endpoint for worked hours, so a Gusto connection is not offered as a timesheet target. Enter those hours in Gusto directly.
A timesheet submission failed — what happened?
The Timesheet Submissions tab shows the reason, such as “Employee not mapped to ADP”. Failed submissions are not retried automatically. Fix the cause, such as mapping the employee or correcting credentials, then use Retry on the failed row.
My compensation change was approved but the salary didn’t update
The change applies on the first daily run on or after its effective date. Check its Scheduled application status:
- Scheduled — the effective date is still in the future.
- Ready to Apply — it will apply on the next daily run.
- Failed — the error is shown on the change. A change stops retrying after 3 failed attempts.
A bonus never overwrites base pay, so the job refuses it; record bonuses in payroll directly. A change for an employee who is no longer active is skipped and left pending.
Why did my connection switch to “Error”?
A failed connection test, employee sync or paycheck retrieval sets a connection to Error. Scheduled syncs run only for active connections, so syncing pauses. Open the connection, fix the credentials, test it again, and then activate it.
The dashboard shows a connection’s health as “—” instead of a percentage
Health is the share of successful syncs over the last 7 days. A dash means there is nothing to measure yet. The connection is inactive, has never synced successfully, or has no sync in that window. It does not mean the connection is broken.
Sync schedule and limits
How often does Payroll Connect sync automatically?
Set Automatic sync frequency on the connection’s edit page: Hourly, Daily (the default), Weekly, or Manual only — never sync on a schedule. A scheduler checks every 15 minutes, so a sync starts within 15 minutes of becoming due. Scheduled syncs import employees and paychecks only. Sync-error emails are controlled by Email on sync errors, on by default. With no Notification email set, they go to up to 5 admins.
Are there limits I should know about?
| What | Limit |
|---|---|
| Timesheets submitted at once from the page | 25 |
| Timesheets per background run | 200 |
| Sync-error email recipients when no address is set | 5 admins |
| Connection health window | 7 days |
| Identity confirmation for pay data and tax documents | 15 minutes |
| Automatic attempts to apply an approved compensation change | 3 |
More help
- Payroll Connect Overview
- Ask AI — the assistant answers Payroll Connect questions from these articles.