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 Admin → Apps → All Apps and must configure at least one provider connection before anything works.
• What it is not: Payroll Connect does not calculate payroll. If you want MangoApps to prepare gross pay from approved timesheets for a processor that takes a file, use Payroll Prep instead. The two are separate apps; enabling one does not enable the other.

2. Standing it up

1. Go to Admin → Apps → All Apps and enable Payroll Connect.
2. Open Payroll Connect → Connections and click the card for your provider (ADP Workforce Now, Workday HCM, Gusto, BambooHR, Paychex, Infor CloudSuite HCM, or Custom Integration; MangoPay is a demo provider for trying the app with sample data).
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 Draft to Connected and enables scheduled syncing. A failing test moves it to Error and stops all scheduled syncs. To recover, fix the credentials under Edit, use Test Connection, then click Activate — a passing test alone does not restart an Error or Inactive connection.
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 see their pay on My Paychecks (and the Payroll Connect tab on the phone) 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: Draft (just created, not yet tested), Connected (credentials validated, syncing enabled), Inactive (paused by an admin with Pause), and Error (the last test or sync failed). Only connected connections are picked up by the scheduled sync. Employees do not see paychecks from a Draft or Inactive connection.

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 on My Paychecks, 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 company admin approves or rejects it. Nobody can approve a change they requested or a change to their own pay. Once approved, a daily job applies a salary change to the employee’s compensation record on its effective date automatically; a bonus is recorded but not applied to pay. Until that approval happens, the change sits in the queue and is not applied. The exception is a step increase raised automatically by a step schedule: its new pay is already in place when it reaches the queue, so approving acknowledges it and rejecting records an objection without undoing it.

HRIS sync — a secondary data channel. When your organization has an HRIS integration configured under Admin → Organization → 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. The platform-wide Hide Pay Amounts setting (Admin › General Settings) is honored on the web and on the phone: when on, employees see no paycheck or salary figures, and the paycheck dashboard widgets are suppressed.

Who can do what — 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, Compensation Changes and the HRIS pages. 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. Employees see their own paychecks on My Paychecks (web and phone) 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 Prep: Payroll Connect sends data to and receives data from your external payroll provider. Payroll Prep turns approved timesheets into a gross-pay report inside MangoApps — it does not calculate taxes or net pay, and it does not pay anyone. They share no connections and no settings, and neither reads the other’s records. They meet in Ask AI: when Payroll Connect holds an employee’s paychecks, Payroll Prep’s Payroll Agent answers “my last paycheck” from them, as the Personal Agent does, and lists year-end tax forms from Payroll Connect’s providers.

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 Submitted (delivered to the provider); 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 sends up to 200 of the oldest waiting timesheets per run.
5. On a new connection, set Send timesheets ending on or after on its Edit page to the first pay period that provider pays, so timesheets already paid another way are not offered or sent. A timesheet already delivered through another connection is marked Already delivered through … and the background run skips it unless you select it.

Retrieving paychecks

1. Go to Payroll Connect → Connections → (your connection) → Paychecks and click Retrieve paychecks, or use the Dashboard’s Retrieve Paychecks quick action.
2. The retrieval pulls recent paychecks from the provider. BambooHR has no paycheck API and Infor syncs employees only, so neither offers this.
3. Retrieved paychecks appear under the Paychecks tab and become visible to employees on My Paychecks.

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 stop it being applied. A step increase raised automatically is already in pay: approving acknowledges it, and rejecting records an objection without undoing it.
5. Changed your mind after approving? Open the change and use Withdraw this approved change (a reason is required). It works until the daily job applies the change; after that, correct the pay in Salary Management.

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; later syncs do not queue that person again unless you Reopen the request.
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	Connection edit page	Daily	How often the scheduled sync runs. Choices: Hourly, Daily, Weekly, or Manual only.
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.
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.

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.