Payroll Connect FAQ
Answers to common setup and operating 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. Every feature — employee sync, paycheck import, timesheet submission, and compensation changes — requires at least one active connection to a payroll provider. Create a connection on the Connections tab, enter your provider credentials, test the connection, then activate it.
Which payroll providers can I connect to?
Payroll Connect includes built-in connectors for ADP Workforce Now, Workday HCM, Gusto, BambooHR, and Paychex. You can also set up a Custom Integration connector with your own API base URL, authentication method, and endpoints. A Merge.dev partner connector is available for additional HRIS providers. MangoPay is included only as a demonstration provider with sample data for evaluating the app.
Who can access the admin side of Payroll Connect?
You need to be a business Admin or above, or have been granted App Admin status for Payroll Connect. Non-admin employees see only their own paychecks and submissions on mobile and on the employee paycheck page — they cannot access the dashboard, connections, salary management, or compensation change approval queue.
Permissions and access
Can I hide pay amounts from employees entirely?
Yes. The platform-wide Hide pay amounts setting (in General Settings) removes paycheck figures from every employee-facing surface: the employee paycheck page, the mobile paycheck screen, the paycheck dashboard widgets, and the compensation profile tab. Admins are exempt and continue to see all figures.
Why does viewing salary or paycheck data ask me to re-verify my identity?
Salary and paycheck amounts are classified as sensitive data. The admin surfaces — Salary Management, Compensation Changes, and the per-connection Paychecks view — require a recently re-verified (step-up) session. If your session elevation has lapsed, you are prompted to re-verify before the figures are shown. Every reveal is also recorded in the audit log.
Day-to-day
How are employees matched between MangoApps and the provider?
During setup, you configure field-level mappings on the Field Mappings page of a connection. On each employee sync, the system matches by work email first, then personal email, then external employee ID. You can also map employees manually on the Employee Mappings page: search for an unmapped employee, enter their provider employee ID, and save.
What happens when a sync discovers a new employee in the provider?
New hires from the provider land in an Import Requests queue on the connection’s page, with a status of Pending review. An admin reviews the employee data, then approves (which creates a MangoApps user and an employee mapping) or rejects with a reason. Employees are never auto-created unless you turn on the Auto-create users setting in Import Settings.
How do I push approved timesheets to my payroll provider?
Open the Timesheet Submissions tab. Select the target connection, review the list of approved timesheets awaiting submission, then submit them individually or in bulk. For large batches (more than 25 timesheets), use Queue in background to run the push as a background job. The cap for a single background run is 200 timesheets. Only real-data timesheets are offered — sample and demo timesheets are excluded.
How does the compensation change approval pipeline work?
Someone in your organization creates a compensation change (salary increase, decrease, bonus, promotion, demotion, or adjustment) with an effective date. It starts at Pending status. A different admin reviews and approves or rejects it on the Compensation Changes tab — the person who requested the change cannot approve it themselves. Once approved, a daily job automatically applies it on the effective date: the employee’s salary record is updated, a compensation history entry is created, and both the employee and the requester receive an in-app notification.
Can I disable specific sync operations on a connection without deactivating the whole connection?
Yes. Each connection has three toggles that default to on: Paycheck retrieval, Timesheet sync, and Compensation changes. Turning one off means the scheduled sync skips that operation. The connection stays active and other operations continue to run.
When something looks wrong
“My pay stub isn’t showing up” — what should I tell the employee?
Paychecks come from the connected provider, not from MangoApps directly. Check that (1) the connection is active and has synced recently (look at the last sync date on the Connections tab), (2) the employee is mapped to their provider record on the connection’s Employee Mappings page, and (3) paycheck retrieval is enabled for that connection. If the provider is BambooHR, note that BambooHR does not have a paycheck API, so paychecks cannot be imported from it.
A timesheet submission failed — what happened?
Failed submissions are flagged on the Timesheet Submissions tab with a human-readable reason. Common causes include: the employee is not mapped to the provider, the connection credentials are invalid (re-test the connection), the provider timed out (try again in a few minutes), or the provider is rate-limiting requests. Failed timesheets can be re-submitted; they are not retried automatically.
My compensation change was approved but the salary didn’t update
The daily application job runs once per day. If the effective date is today or has already passed, the change will be applied on the next daily run. Check the change’s Scheduled application status: Ready to Apply means it is queued for the next run, Scheduled means the effective date is still in the future, and Failed means something went wrong — the error is shown on the record. If the employee is no longer active in the business, the change is skipped.
The dashboard says a connection’s health is “—” instead of a percentage
The health percentage is calculated from sync logs over the last 7 days. A dash means there is nothing to measure: the connection is not active, has never had a successful sync, or has no sync log within that window. It does not mean the connection is broken — activate it and run a sync, and the health score will appear.
Why did my connection switch to “Error” status after a test?
A failed connection test sets the connection to Error status. The scheduled sync only sweeps active connections, so syncing pauses until you fix the credentials and re-activate. Open the connection, update the credentials, re-test, and once the test passes, activate the connection again.
Sync schedule and limits
How often does Payroll Connect sync automatically?
Each connection has a sync frequency set at creation: Hourly, Daily (the default), or Weekly. A scheduler checks every 15 minutes for overdue connections and enqueues a sync when the window has elapsed. The worst-case delay after a connection becomes overdue is 15 minutes. Only employee and paycheck syncs run on the schedule — timesheet submission is always admin-initiated.
What are the default settings on a new connection?
A new connection is created with: sync frequency Daily, paycheck retrieval enabled, timesheet sync enabled, compensation changes enabled, batch size 50 records, API timeout 300 seconds, and sync-error notifications enabled. The connection status starts as Setup — you must activate it before syncing begins.
Are there limits I should know about?
The sync batch size defaults to 50 records per batch. A single background timesheet submission run is capped at 200 timesheets. Synchronous (in-browser) submission handles up to 25 timesheets before requiring the background queue. Sync-error email notifications are sent to up to 5 admins when no specific notification email is configured. The health dashboard measures a rolling 7-day window.
Licensing
Does Payroll Connect require a licence?
Yes. Payroll Connect requires a licence and is disabled by default. An administrator enables it from the Apps Marketplace. You also need an active account with a supported payroll provider (or a custom API endpoint) to create a connection.
More help
- Payroll Connect Overview
- Ask AI — the assistant answers Payroll Connect questions from these articles.