Payroll Connect App Overview

Payroll Connect

1. What it is

Payroll Connect bridges MangoApps to the external payroll system you already run. It syncs employee records, pushes approved timesheets to your payroll provider, imports paychecks so employees can view their pay stubs, and tracks compensation changes through an approval workflow.

• Enablement: Payroll Connect requires a license. An admin enables it from the Apps Marketplace and must configure at least one provider connection before anything works.
• What it is not: Payroll Connect does not calculate payroll. If you want to run payroll entirely inside MangoApps, use Payroll Processing instead. The two are separate apps; enabling one does not enable the other.

2. Standing it up

1. Go to Apps Marketplace and enable Payroll Connect.
2. Open Payroll Connect → Connections and click the card for your provider (ADP Workforce Now, Workday HCM, Gusto, BambooHR, Paychex, MangoPay, or Custom Integration).
3. Enter your provider’s API credentials (the fields vary by provider) and give the connection a name.
4. Click Test & Activate. A passing test moves the connection from Setup to Active and enables scheduled syncing. A failing test moves it to Error and pauses all scheduled syncs until you fix the credentials and re-test.
5. Go to Connections → (your connection) → Employee Mappings. Click Sync Employees to pull the employee roster from your provider. The sync matches employees by email; unmatched employees appear in the Unmapped list and can be mapped manually.
6. Confirm it worked: the Dashboard shows a card per connection with the employee count, health percentage, and last sync time. Your employees now see a Paychecks tab in their profile once paychecks are retrieved.

What silently does nothing until paired: creating a connection without mapping employees means timesheet submissions and paycheck retrieval have nobody to operate on. Always sync or manually map employees before expecting data to flow.

3. How it fits together

Connections — a connection is a set of credentials and settings that ties MangoApps to one payroll provider. Each provider type can have one connection at a time. A connection has four statuses: Setup (just created, not yet tested), Active (credentials validated, syncing enabled), Inactive (manually paused by an admin), and Error (the last test or sync failed). Only active connections are picked up by the scheduled sync.

Employee mappings — each mapping links one MangoApps user to their identifier in the payroll provider. Mappings are created automatically during an employee sync (matched by email) or manually by an admin. Without a mapping, that employee’s timesheets cannot be submitted and their paychecks cannot be imported.

Example: you connect ADP Workforce Now and sync employees. The sync finds 150 employees in ADP. 140 match a MangoApps user by email and receive an active mapping. The remaining 10 appear in the Unmapped list. You can map them manually by entering each one’s ADP employee number, or you can review them as import requests (see below).

Timesheet submissions — after a timesheet is approved inside the Timesheets app, Payroll Connect can push it outbound to the provider. This is always admin-initiated (from the Timesheet Submissions tab or queued in the background). It is never automatic — the scheduled sync does not submit timesheets, because pushing hours outbound becomes someone’s pay and must not happen as a side effect of a cadence nobody set.

Paychecks — the inbound counterpart: Payroll Connect pulls paycheck data from the provider and stores it. Employees see their pay stubs in their profile, on the mobile app, and in the former-employee portal. Paycheck amounts are treated as sensitive data; viewing them in the admin interface requires a recently verified session (step-up authentication) and every view is logged to the audit trail. Employees can download a PDF pay stub from mobile or desktop.

Compensation changes — these track proposed salary adjustments (raises, promotions, bonuses, adjustments, demotions). They move through an approval workflow: a requester creates the change, and a different admin must approve it. The requester cannot approve their own change. Once approved, a daily job applies the change to the employee’s compensation record on its effective date automatically. Until that approval happens, the change sits in the queue and is never applied.

HRIS sync — a secondary data channel. When your organization has an HRIS integration configured under Admin → Integrations (such as BambooHR, Workday, or another Merge.dev-supported provider), Payroll Connect can browse the imported data in four tabs: Employees, Time Off, Departments, and Employee Payroll Runs. HRIS Settings in Payroll Connect controls which provider to pull from and whether live sync is on or off.

Import requests — when an employee sync finds a person in the provider who has no MangoApps account at all (not just unmapped), the sync can create an import request. Import requests sit in a review queue on the connection’s Import Requests page. An admin approves (which creates the MangoApps user and the mapping in one step) or rejects (a reason is required). Import settings on each connection control whether auto-creation is on or off, which fields are required, and an optional email domain allowlist.

Scheduled sync — a background sweep runs every 15 minutes and checks every active connection. If a connection’s sync frequency window has elapsed (2 hours for hourly, 26 hours for daily, 8 days for weekly), a full sync (employees + paychecks) is enqueued. The sync respects each connection’s per-operation toggles: if paycheck retrieval is off, it syncs employees only and vice versa. Timesheet submission is never part of the scheduled sweep.

Health percentage — the Dashboard and Connections pages show a health percentage per connection. This is the share of sync attempts in the last 7 days that succeeded. A connection that has never synced, is inactive, or has no sync logs in the window shows an em dash instead of a number.

Sensitive data protection — paycheck amounts, salary details, and compensation changes are treated as sensitive pay data. Admin pages that reveal these values require a recently re-verified session (step-up authentication), and every view is written to the audit trail. On mobile, the platform-wide Hide pay amounts setting is also honored: when on, employees see no paycheck or salary figures, and the paycheck dashboard widgets are suppressed.

Who can do what — the admin surfaces (Dashboard, Connections, Paychecks, Timesheet Submissions, Salary Management, Compensation Changes) require Admin or above. The Admin section (HRIS Data and HRIS Settings) additionally requires app admin for Payroll Connect. Employees see their own paychecks in their profile (desktop and mobile) and in the former-employee portal after separation. Employees see only approved and processed compensation changes — pending and rejected proposals are not shown to them.

Payroll Connect vs. Payroll Processing: Payroll Connect sends data to and receives data from your external payroll provider. Payroll Processing runs payroll calculations inside MangoApps. They share no connections, no settings, and no data — enabling one does not affect the other.

4. Running it

Syncing employees

1. Go to Payroll Connect → Connections → (your connection).
2. Click Sync Employees. The sync pulls the roster from the provider, creates mappings for employees matched by email, and reports the count.
3. Review the Unmapped list. For each unmapped employee, you can enter their provider ID to create a manual mapping, or leave them unmapped.

Submitting timesheets to the provider

1. Go to Payroll Connect → Timesheet Submissions.
2. The list shows approved timesheets that have not yet been pushed. Select the timesheets to submit.
3. Click Submit. Each timesheet is pushed to the provider individually. Successful submissions are marked Processed; failures show a human-readable reason (credentials rejected, employee not mapped, provider unreachable) and can be retried.
4. For large batches, use Queue in background — the job processes up to 200 timesheets per run.

Retrieving paychecks

1. Go to Payroll Connect → Connections → (your connection) and click Retrieve Paychecks, or use the Dashboard’s quick action.
2. The sync pulls paycheck data from the provider for the last 30 days by default. You can specify a custom date range.
3. Retrieved paychecks appear under the Paychecks tab and become visible to employees in their profile.

Reviewing compensation changes

1. Go to Payroll Connect → Compensation Changes.
2. Filter by status (Pending, Approved, Rejected, Processed, Cancelled).
3. Open a pending change to see the employee, current salary, proposed salary, change amount, change percentage, and effective date.
4. Approve to allow the daily job to apply the change on its effective date. Reject (a reason is required) to prevent it from ever being applied.

Reviewing import requests

1. Go to Payroll Connect → Connections → (your connection) → Import Requests.
2. Filter by status (Pending, Approved, Rejected). Search by name, email, or provider employee ID.
3. Approve to create the MangoApps user and the employee mapping in one step. Reject with a reason to skip the import.
4. Configure the import policy under Import Settings on the same connection: auto-creation, required fields, and email domain allowlist.

Managing salaries

1. Go to Payroll Connect → Salary Management.
2. The overview shows how many employees have validated salaries, discrepancies between MangoApps and the provider, and employees with no payroll data.
3. Click an employee to see their salary analysis and recent paycheck history (the most recent 12 active paychecks are shown).
4. Export the salary report as CSV from the top of the page.

Viewing sync logs

1. Go to Payroll Connect → Connections → (your connection) → Logs.
2. Each log shows the sync type, status, start time, duration, and record counts.
3. Filter to errors only to see recent failures. Error summaries never include raw provider data — they describe what to do (re-test credentials, check configuration, retry later).

5. Settings

Payroll Connect has no app-level settings in the marketplace configuration. All settings live on each individual connection.

Per-connection sync settings

Setting	Where	Default	What it changes
Sync frequency	Set at connection creation	Daily	How often the scheduled sync runs. Choices: Hourly, Daily, Weekly.
Timesheet sync enabled	Connection sync settings	On	Whether approved timesheets can be submitted through this connection.
Paycheck retrieval enabled	Connection sync settings	On	Whether paychecks can be pulled from this connection.
Compensation changes enabled	Connection sync settings	On	Whether compensation changes can be processed through this connection.
Auto map employees	Connection sync settings	On	Whether employee sync automatically creates mappings for email-matched employees.
Retry failed submissions	Connection sync settings	On	Whether the sync job retries failed operations.
Max retry attempts	Connection sync settings	3	How many times the sync job retries a transient failure before giving up.
Notification email	Connection edit page	Blank (falls back to business admins)	Who receives sync-error email notifications. When blank, up to 5 business admins are notified.
Notify on sync errors	Connection edit page	On	Whether an email is sent when a sync fails.

Per-connection default settings (created automatically)

Setting	Default	What it changes
Sync frequency	Daily	Redundant with the sync frequency in the connection sync settings above; the per-setting row mirrors it.
Timeout	300 seconds	API timeout for provider calls.
Enable notifications	On	Whether sync notifications are sent.
Batch size	50	Number of records processed per batch during sync.

HRIS settings (app-admin only)

Setting	Where	Default	What it changes
HRIS sync provider	Payroll Connect → Admin → HRIS Settings	None selected	Which connected HRIS integration to pull data from. Selecting a provider turns live sync on; clearing it turns sync off.
Employee creation policy	Payroll Connect → Admin → HRIS Settings	Skip missing	What happens when an imported employee has no matching MangoApps user. Currently only “Skip missing” is implemented (unmatched employees are recorded as orphaned).

6. More help

• Payroll Connect FAQ — specific setup and operating questions
• Ask AI — the assistant answers questions about Payroll Connect from these articles.