Payroll App Overview

Connect your payroll platforms, sync employee data, and put pay stubs at every employee’s fingertips — all from one unified hub.

---

What Is Payroll Connect?

Payroll Connect is the workforce integration hub that bridges MangoApps with your external payroll providers. Instead of replacing your payroll system, it connects to it — syncing employee records, retrieving paychecks, submitting timesheets, and tracking compensation changes across providers like ADP, Workday, Gusto, BambooHR, Paychex, and MangoPay. Every connection is encrypted, health-monitored, and audit-logged so HR and payroll admins always know the state of their data.

Core Value Proposition:

• 🔗 Multi-Provider Hub — Connect ADP, Workday, Gusto, BambooHR, Paychex, MangoPay, or any custom provider from a single dashboard
• 📄 Pay Stub Self-Service — Employees view paychecks, deductions, taxes, and YTD totals without contacting HR
• 🔄 Bidirectional Sync — Push timesheets to payroll and pull paychecks back with automated scheduling
• 🛡️ Encrypted & Audited — Connection credentials are encrypted at rest; every sync is logged with success rates and error details

---

At a Glance

🔌 Supported Providers	📊 Sync Types	📋 Report Formats	🤖 AI Agent
7 (ADP, Workday, Gusto, BambooHR, Paychex, MangoPay, Custom)	5 (Employees, Timesheets, Paychecks, Compensation, Full)	3 (CSV, PDF, JSON)	Payroll Agent (Ask AI)

Perfect For:

• 🏢 Multi-Entity Orgs — Connect different payroll providers per division or subsidiary
• 🏭 Hourly Workforces — Push timesheet hours directly into payroll for accurate pay runs
• 📊 Finance & HR Teams — Salary validation, discrepancy detection, and compensation audit trails
• 👤 Every Employee — Self-service access to pay stubs, deduction breakdowns, and tax documents

---

How It Works

Provider Connection Flow

┌─────────────────────────────────────────────────────────────────────────┐
│                   PAYROLL PROVIDER CONNECTION FLOW                       │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────┐   ┌──────────────┐   ┌──────────────┐   ┌────────────┐  │
│  │  ADMIN   │──▶│ SELECT       │──▶│ ENTER API    │──▶│ TEST       │  │
│  │ Starts   │   │ Provider     │   │ Credentials  │   │ CONNECTION │  │
│  │ Setup    │   │ (ADP, Gusto  │   │ (Encrypted   │   │ (Validate  │  │
│  │          │   │  Workday...) │   │  at rest)    │   │  Access)   │  │
│  └──────────┘   └──────────────┘   └──────────────┘   └─────┬──────┘  │
│                                                              │         │
│                  ┌───────────────────────────────────────────┘         │
│                  ▼                                                      │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐              │
│  │ MAP FIELDS   │──▶│ SYNC         │──▶│ ACTIVATE     │              │
│  │ MangoApps ◀─▶│   │ EMPLOYEES    │   │ Scheduled    │              │
│  │ Payroll      │   │ Auto-match   │   │ Syncs        │              │
│  │ Fields       │   │ by email     │   │ (Daily/      │              │
│  │              │   │              │   │  Weekly)     │              │
│  └──────────────┘   └──────────────┘   └──────────────┘              │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Data Sync Ecosystem

┌───────────────────────────────────────────────────────────────────────┐
│                  PAYROLL CONNECT DATA ECOSYSTEM                        │
├───────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  EXTERNAL PROVIDERS          PAYROLL CONNECT         MANGOAPPS        │
│                                                                       │
│  ┌─────────────┐         ┌──────────────────┐                        │
│  │  ADP        │◀───────▶│                  │    ┌──────────────┐    │
│  ├─────────────┤         │   CONNECTION      │───▶│  EMPLOYEE    │    │
│  │  Workday    │◀───────▶│   MANAGER         │    │  PROFILES    │    │
│  ├─────────────┤         │                  │    └──────────────┘    │
│  │  Gusto      │◀───────▶│  ┌────────────┐  │                        │
│  ├─────────────┤         │  │ Employee   │  │    ┌──────────────┐    │
│  │  BambooHR   │◀───────▶│  │ Mapping    │  │───▶│  TIMESHEETS  │    │
│  ├─────────────┤         │  ├────────────┤  │    └──────────────┘    │
│  │  Paychex    │◀───────▶│  │ Field      │  │                        │
│  ├─────────────┤         │  │ Mapping    │  │    ┌──────────────┐    │
│  │  MangoPay   │◀───────▶│  ├────────────┤  │───▶│  PAYCHECKS   │    │
│  ├─────────────┤         │  │ Sync       │  │    └──────────────┘    │
│  │  Custom API │◀───────▶│  │ Scheduler  │  │                        │
│  └─────────────┘         │  └────────────┘  │    ┌──────────────┐    │
│                          │                  │───▶│  COMPENSATION│    │
│                          └──────────────────┘    │  HISTORY     │    │
│                                                  └──────────────┘    │
│                                                                       │
└───────────────────────────────────────────────────────────────────────┘

Paycheck Retrieval & Display Flow

┌─────────────────────────────────────────────────────────────────┐
│                 PAYCHECK DATA PIPELINE                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Provider API ──▶ Retrieve ──▶ Parse & Store ──▶ Employee View  │
│                                                                 │
│  ┌─────────┐    ┌──────────┐    ┌───────────┐    ┌──────────┐ │
│  │ Gross   │    │ Earnings │    │ Federal   │    │ Net Pay  │ │
│  │ Pay     │ =  │ Detail   │ -  │ + State   │ -  │ (Take    │ │
│  │         │    │ Regular  │    │ + SS +    │    │  Home)   │ │
│  │         │    │ Overtime │    │ Medicare  │    │          │ │
│  │         │    │ Premium  │    │ Taxes     │    │          │ │
│  └─────────┘    └──────────┘    └───────────┘    └──────────┘ │
│                                       │                        │
│                                       ▼                        │
│                                 ┌───────────┐                  │
│                                 │ Benefits  │                  │
│                                 │ Deductions│                  │
│                                 │ (Health,  │                  │
│                                 │  401k,    │                  │
│                                 │  HSA...)  │                  │
│                                 └───────────┘                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

Key Features

🔌 Multi-Provider Connections

Connect to any combination of payroll providers simultaneously. Each connection is independently configured, monitored, and secured.

Provider	Integration Type	Key Capabilities
ADP Workforce Now	Built-in	Employee sync, paycheck retrieval, compensation changes
Workday HCM	Built-in	Full HCM data sync, paycheck data, workforce analytics
Gusto	Built-in	Employee sync, payroll data retrieval, benefits deductions
BambooHR	Built-in	Employee records, paycheck import, HR data sync
Paychex	Built-in	Employee mapping, pay data retrieval, tax document access
MangoPay	Built-in	Native integration with demo/sandbox mode for testing
Custom API	Built-in	Connect any REST-based payroll system with field mapping

Each connection tracks its own health score (0-100%) calculated from the ratio of successful syncs over the last 7 days. Connections are flagged as overdue based on their configured frequency — hourly, daily, or weekly.

💡 Pro Tip: Use the MangoPay provider in sandbox mode to test your integration setup before connecting a live payroll system.

---

📄 Paycheck Management

Paychecks are pulled from connected providers and stored locally, giving employees instant self-service access to their pay history.

Feature	Details
Pay Stub View	Gross pay, net pay, total deductions, total taxes, and hours worked
Earnings Breakdown	Regular pay, overtime pay, and premium pay itemized separately
Tax Breakdown	Federal income tax, state income tax, Social Security, and Medicare
Deductions Breakdown	Health insurance, retirement (401k), HSA, and all other deductions
Year-to-Date Totals	Running YTD gross, net, taxes, and deductions across all paychecks
Pay Period Types	Weekly, biweekly, semi-monthly, and monthly pay periods supported
PDF Pay Stubs	Attached PDF files for download from the paycheck detail view
Benefits Integration	When Benefits Management is enabled, benefit deductions are shown inline

Paycheck Statuses:

Active ──▶ Voided (reversed paycheck)
   │
   └──▶ Corrected (amended paycheck)

Filtering & Views:

• Filter by employee, connection, status, or date range
• View paychecks by employee with per-person YTD summaries
• Bulk retrieve paychecks across all active connections in one action

---

🗂️ Employee Mapping & Field Mapping

Before data can flow between systems, MangoApps employees must be mapped to their payroll provider identities.

Mapping Type	What It Does
Employee Mapping	Links a MangoApps user to an external employee ID and code
Field Mapping	Maps MangoApps fields (email, name, department) to provider field names
Auto-Match	Automatically maps employees by email address during sync
Data Preview	Preview how provider data transforms using current field mappings

Default Field Mappings:

MangoApps Field	Default Provider Field
Email	email
First Name	first_name
Last Name	last_name
Employee ID	employee_id
Department	department
Position	position
Hire Date	hire_date
Hourly Rate	hourly_rate
Salary	salary

💡 Pro Tip: Use the “Preview Data” feature to verify your field mappings with sample data before running a full employee sync.

---

📤 Timesheet Submission

Approved timesheets from MangoApps are submitted to the connected payroll provider for pay processing.

Status	Description
Pending	Timesheet ready for submission
Submitted	Sent to payroll provider, awaiting confirmation
Processed	Payroll provider confirmed receipt and processing
Failed	Submission failed — eligible for retry
Cancelled	Manually cancelled by admin

Key Capabilities:

• Automatic submission of approved timesheets with total hours and pay calculations
• Overdue detection — submissions pending for more than 24 hours are flagged
• Retry mechanism for failed submissions with full error logging
• External submission ID tracking links each submission back to the provider

---

💰 Salary Management & Compensation Changes

Track, validate, and sync salary changes between MangoApps and payroll providers.

Feature	Details
Salary Overview	Dashboard showing total employees, validated salaries, discrepancies, and missing data
Discrepancy Detection	Compares MangoApps salary records against payroll-calculated values to find mismatches
Employee Salary Detail	Per-employee view with payroll history, compensation history, and analysis
Bulk Salary Review	Validate all employee salaries at once with pagination and summary statistics
Salary Updates	Update salaries with effective dates, change reasons, and audit trails
Report Export	Export salary reports to CSV or JSON for comprehensive or filtered employee sets

Compensation Change Types:

Change Type	Description
Salary Increase	Standard pay raise
Salary Decrease	Pay reduction
Bonus	One-time bonus payment
Promotion	Salary change tied to a promotion
Demotion	Salary change tied to a demotion
Adjustment	General compensation adjustment

Compensation Change Lifecycle:

Pending ──▶ Approved ──▶ Processed (synced to payroll)
   │            │
   │            └──▶ Scheduled ──▶ Auto-Applied on Effective Date
   │
   └──▶ Rejected
   └──▶ Cancelled

Future-dated compensation changes are automatically applied on their effective date by a background job. The job updates the employee’s annual salary, recalculates the hourly rate, and creates a compensation history record for the audit trail.

---

✅ Approval Workflows

Configurable approval workflows govern how payroll-related changes are reviewed and processed.

Workflow Type	What It Governs
Compensation Change	Salary increases, decreases, bonuses, and promotions require approval
Timesheet Approval	Timesheet submissions reviewed before sending to payroll
Paycheck Review	Paycheck data reviewed after retrieval from provider
Employee Onboarding	New employee import requests require admin review
Custom	User-defined workflows with configurable rules

Each workflow supports notification settings with configurable channels (email, in-app) and rule-based triggering.

---

🔄 Sync Engine & Health Monitoring

The sync engine runs as background jobs with configurable frequency, automatic retries, and comprehensive logging.

Sync Type	What It Does
Employees	Pulls employee records from provider, maps to MangoApps users
Paychecks	Retrieves paycheck data for a date range (default: last 30 days)
Timesheets	Pushes approved timesheets to the payroll provider
Compensation	Syncs salary changes to the external system
Full Sync	Runs employee + paycheck sync in sequence

Sync Settings (per connection):

Setting	Default	Description
Sync Frequency	Daily	How often automatic syncs run
Timesheet Sync	Enabled	Push timesheets to provider
Paycheck Retrieval	Enabled	Pull paychecks from provider
Compensation Changes	Enabled	Sync salary changes
Auto-Map Employees	Enabled	Automatically match by email
Retry Failed	Enabled	Retry failed submissions
Max Retry Attempts	3	Exponential backoff retries
Timeout	300s	API call timeout
Batch Size	50	Records per batch

Health Monitoring Dashboard:

• Real-time health percentage per connection (based on 7-day success rate)
• Overdue sync detection based on configured frequency
• Error connection count and recent sync failure log
• Quick actions: test connection, sync employees, retrieve paychecks

---

📥 Employee Import Requests

When a payroll sync discovers employees in the external system that don’t exist in MangoApps, import requests are created for admin review.

Request Type	Description
New Employee	Employee exists in payroll but not in MangoApps
Update Employee	Employee data has changed in payroll and needs updating

Import Request Lifecycle:

Pending Review ──▶ Approved (user created + mapping added)
       │
       ├──▶ Rejected (with reason)
       └──▶ Cancelled

Import Settings (per connection):

• Orphaned employee handling policy
• Auto-create users toggle
• Default role for imported users
• Required fields enforcement
• Email domain whitelist

---

📊 Payroll Reports

Generate payroll reports for any date range, filtered by location, department, or individual employees.

Report Data	Details
Per Employee	Hourly rate, regular hours, overtime hours, regular pay, overtime pay, total pay, shifts count
Overtime Calculations	Configurable weekly threshold, overtime multiplier (default 1.5x), double-time support
Aggregated Totals	Total regular pay, overtime pay, premium pay, total hours across all employees
Leave Data	Leave balance and leave used during the pay period
Export Formats	CSV, PDF, and JSON with location-filtered and date-ranged outputs

Reports are processed asynchronously via background jobs. When complete, the report author receives an email notification.

---

🤖 AI Payroll Agent

The Payroll Agent integrates with Ask AI to let employees query their pay information using natural language.

Tool	What It Does
View Pay Stubs	Retrieve recent pay stubs with gross/net pay and hours
Pay Stub Details	Drill into a specific paycheck for tax and deduction breakdown
View Deductions	List all active deductions with amounts, frequency, and tax treatment
Tax Documents	Access W-2, 1099, and other tax documents by year
Payment History	View payment history with annual totals
Pay Schedule	Check upcoming pay dates and pay frequency

Example Questions:

• “Show me my last pay stub”
• “When is the next payday?”
• “Download my W-2 form”

💡 Pro Tip: The Payroll Agent only surfaces the asking employee’s own data — it cannot access other employees’ payroll information.

---

🔗 Benefits Integration

When the Benefits Management app is enabled, payroll and benefits work together to provide a complete picture of employee compensation.

Integration Point	What It Does
Paycheck Deductions	Benefits deductions (medical, dental, vision, 401k, HSA) appear inline on pay stubs
Wellness Discounts	Wellness program discounts are applied to benefit deduction calculations
Per-Period Costs	Monthly benefit costs are automatically split by pay frequency (biweekly, semi-monthly, monthly)
Tax Treatment	Pre-tax and post-tax deductions are tagged based on benefit category

---

User Roles & Permissions

Action	Employee	Manager	HR	Admin
View own paychecks	✅	✅	✅	✅
View own deductions and taxes	✅	✅	✅	✅
Access pay stubs via Ask AI	✅	✅	✅	✅
View own YTD totals	✅	✅	✅	✅
View team paycheck summaries	❌	❌	✅	✅
Manage payroll connections	❌	❌	❌	✅
Configure field mappings	❌	❌	❌	✅
Sync employees and paychecks	❌	❌	❌	✅
Approve/reject import requests	❌	❌	❌	✅
Manage salary and compensation	❌	❌	❌	✅
Generate payroll reports	❌	❌	✅	✅
Configure approval workflows	❌	❌	❌	✅
View sync logs and health	❌	❌	❌	✅
Export salary reports	❌	❌	✅	✅

---

Getting Started

For Employees

1. View Your Paychecks — Navigate to Payroll Connect and open the Paychecks section to see your pay history
2. Check a Pay Stub — Click any paycheck to see earnings, taxes, deductions, and hours breakdowns
3. Review YTD Totals — Each paycheck shows your year-to-date gross, net, taxes, and deductions
4. Ask AI — Type “Show me my last pay stub” in Ask AI for quick payroll answers
5. Download PDFs — Download pay stub PDFs when available for your records

For HR Staff

1. Run Reports — Generate payroll reports for any pay period with location and department filters
2. Review Salary Data — Use Salary Management to compare MangoApps and payroll provider salary records
3. Export Data — Export salary reports in CSV or JSON for external analysis
4. Monitor Changes — Track recent compensation changes and their approval status

For Administrators

1. Connect a Provider — Go to Dashboard > Connections > New Connection and select your payroll provider
2. Configure Credentials — Enter API credentials (encrypted at rest) and test the connection
3. Map Fields — Set up field mappings between MangoApps and your provider’s data schema
4. Sync Employees — Run the initial employee sync to map staff between systems
5. Activate Scheduling — Configure daily, weekly, or hourly automatic syncs
6. Set Import Policies — Define how orphaned employees and new payroll users are handled
7. Review Health — Monitor the dashboard for connection health, sync status, and error alerts

---

Best Practices

• ✅ Test connections in sandbox mode before connecting production payroll systems
• ✅ Preview field mappings with sample data to catch transformation issues early
• ✅ Set up sync error notifications so admins are alerted immediately when a sync fails
• ✅ Run employee syncs before paycheck retrieval to ensure all employees are mapped
• ✅ Review import requests promptly — orphaned employees in payroll may indicate onboarding gaps
• ✅ Use bulk salary review periodically to catch discrepancies between MangoApps and payroll
• ✅ Enable auto-map by email to minimize manual employee mapping work
• ✅ Schedule syncs during off-peak hours to reduce API rate-limit risks with your provider
• ✅ Monitor the health dashboard daily — a drop below 75% signals recurring sync failures
• ✅ Keep connection credentials current — expired API keys cause cascading sync errors

---

Related Resources

• Compensation Management Overview — Manage compensation structures, merit increases, and total compensation packages
• Timesheet Export Overview — Export approved timesheets to feed into payroll processing
• Benefits Management Overview — Benefits deductions integrate directly into paycheck displays
• Time & Attendance Overview — Clock-in data flows through timesheets into payroll

---

Accurate, timely payroll is the backbone of employee trust — Payroll Connect bridges your systems so every pay stub is one click away.