Payroll Processing App Overview
Run payroll in-house with MangoApps as the system of record — an in-house payroll engine for gross-to-net calculation, deductions, multi-state tax compliance, and direct deposit. This app is in active development. Today it ships a Payroll Reports tool for admins and a read-only Payroll AI Agent that surfaces paycheck data; the full engine — deductions, tax calculation, payment distribution, and year-end filings — is planned and not yet available.
⚠️ Status & Roadmap — Read This First
Payroll Processing is a forward-looking marketplace app that groups together several features as they ship. Most capabilities described in the marketplace directory are labeled “Planned” and are not usable today. Please read this section before enabling the app.
What is actually built today
| Capability | Where it lives | Status |
|---|---|---|
| Payroll Reports — generate CSV/PDF/JSON reports of hours and pay from approved timesheets | Admin → Payroll (Admin::PayrollController) |
✅ Built |
| Pay period settings — configure weekly, biweekly, semi-monthly, or monthly pay periods | Admin → General Settings → Payroll Settings | ✅ Built |
| Payroll AI Agent — employees ask the Ask AI assistant about pay stubs, deductions, tax documents, and year-to-date totals | Ask AI sidebar | ✅ Built (reads from Payroll Connect data) |
| Location-based access control — admins can scope payroll report visibility by location | IntegratedPermissionService |
✅ Built |
What is NOT built yet
The in-house payroll engine itself — calculating gross-to-net, running payroll, withholding taxes, issuing direct deposits, and filing year-end forms — is on the roadmap. These capabilities are listed in the app directory with supported: false, note: 'Planned'. Do not enable this app expecting to run payroll end-to-end today.
What to use today if you need payroll
If you need to run payroll now, use Payroll Connect to integrate MangoApps with an existing payroll provider (ADP Workforce Now, Workday HCM, Gusto, BambooHR, Paychex, or MangoPay). Payroll Connect is production-ready and is where paycheck data actually comes from today.
Payroll Processing vs. Payroll Connect — which do I pick?
This is the single most common question. The two apps solve different problems:
| Question | Answer |
|---|---|
| I already have ADP / Gusto / Workday / Paychex and want MangoApps to sync with it | Use Payroll Connect. Production-ready today. |
| I want MangoApps to be our payroll system — calculate taxes, cut checks, file W-2s | Use Payroll Processing — but note it’s in early preview. Track the roadmap below. |
| I just want employees to see their pay stubs in MangoApps | Use Payroll Connect — it imports paychecks from your provider for self-service viewing. |
| I want admins to download payroll-ready hours reports from Timesheets | Either app works — the Payroll Reports tool described below ships with this app. |
The two apps can run simultaneously during a transition. Payroll Connect can be disabled once Payroll Processing is mature enough to run your active payroll.
Feature Evidence Table
Every capability in Payroll Processing, cross-referenced against the code. Legend:
- ✅ Built — wired up and usable today
- 🚧 Planned — listed in directory metadata as
supported: false, note: 'Planned' - ❌ Not Available — not in the codebase, not on the near-term roadmap
Current capabilities
| Feature | Status | Code Reference |
|---|---|---|
| Payroll Reports (index/show/download) | ✅ Built | src/app/controllers/admin/payroll_controller.rb |
| CSV / PDF / JSON report export | ✅ Built | PayrollReport::FORMATS in payroll_report.rb |
PayrollReport model with totals, filters, metadata |
✅ Built | src/app/models/payroll_report.rb |
| Per-employee line items (regular / overtime / premium hours & pay) | ✅ Built | src/app/models/payroll_report_item.rb |
| Location-scoped report access | ✅ Built | Admin::PayrollController#require_admin_manager_or_payroll_permission |
| Report regeneration with synchronous processing | ✅ Built | PayrollReportService, Admin::PayrollController#regenerate |
| Report deletion (creator + admin) | ✅ Built | Admin::PayrollController#destroy |
| Pay period settings (weekly / biweekly / semi-monthly / monthly) | ✅ Built | BusinessPayPeriodSetting |
| Email notification when a report is ready | ✅ Built | PayrollMailer.report_ready |
| Employee paycheck self-service (read Payroll Connect paychecks) | ✅ Built | Employee::PaychecksController |
| Payroll AI Agent — 8 read-only tools | ✅ Built | src/app/services/agents/payroll_agent.rb |
| Agent tools: pay stubs, deductions, tax docs, YTD, compare stubs | ✅ Built | Agents::ToolRegistry::Payroll::TOOLS |
Planned capabilities (roadmap)
All capabilities below are marked supported: false, note: 'Planned' in src/lib/marketplace_app_definitions/directory/payroll.rb. They describe the aspirational in-house payroll engine.
| Category | Feature | Status |
|---|---|---|
| Gross Pay | Import approved timesheets from Timesheets app | 🚧 Planned |
| Gross Pay | Regular / overtime / premium pay calculation | 🚧 Planned |
| Gross Pay | Salary, hourly, piece-rate support | 🚧 Planned |
| Gross Pay | Bonus, commission, one-time earnings | 🚧 Planned |
| Gross Pay | Retroactive and back-pay calculations | 🚧 Planned |
| Gross Pay | Multi-rate pay (differential rates) | 🚧 Planned |
| Deductions | 401(k), 403(b), HSA, FSA, commuter benefits | 🚧 Planned |
| Deductions | Roth 401(k) and other after-tax | 🚧 Planned |
| Deductions | Employer contribution matching | 🚧 Planned |
| Deductions | Wage garnishments with priority ordering | 🚧 Planned |
| Deductions | Custom deduction types with per-employee overrides | 🚧 Planned |
| Deductions | Benefits Management app auto-sync | 🚧 Planned |
| Tax | Federal income tax (IRS Publication 15-T) | 🚧 Planned |
| Tax | FICA (Social Security + Medicare) | 🚧 Planned |
| Tax | FUTA tracking | 🚧 Planned |
| Tax | State income tax, all 50 states | 🚧 Planned |
| Tax | SUTA per-state rates | 🚧 Planned |
| Tax | Local tax (city, county, school district) | 🚧 Planned |
| Tax | Multi-state allocation for remote employees | 🚧 Planned |
| Tax | W-4 and state equivalent forms per employee | 🚧 Planned |
| Payments | ACH direct deposit (same-day or next-day) | 🚧 Planned |
| Payments | Multi-account split deposit | 🚧 Planned |
| Payments | Printed check generation with MICR encoding | 🚧 Planned |
| Payments | Pay card / payroll debit card | 🚧 Planned |
| Payments | Paper pay stubs | 🚧 Planned |
| Payments | Digital pay stubs via self-service portal | 🚧 Planned |
| Payroll Runs | Scheduled runs on configurable pay periods | 🚧 Planned |
| Payroll Runs | Off-cycle / bonus / termination runs | 🚧 Planned |
| Payroll Runs | Preview mode with gross-to-net breakdown | 🚧 Planned |
| Payroll Runs | Dual-approval sign-off workflow | 🚧 Planned |
| Payroll Runs | Void and reissue for corrected paychecks | 🚧 Planned |
| Payroll Runs | Audit log per run (actor, timestamp, totals) | 🚧 Planned |
| Compliance | Form 941 quarterly federal return | 🚧 Planned |
| Compliance | Form 940 annual FUTA return | 🚧 Planned |
| Compliance | W-2 generation and electronic filing | 🚧 Planned |
| Compliance | 1099-NEC and 1099-MISC for contractors | 🚧 Planned |
| Compliance | State new-hire reporting | 🚧 Planned |
| Compliance | Workers’ comp classification and reporting | 🚧 Planned |
| Compliance | GL journal export (QuickBooks, NetSuite, CSV) | 🚧 Planned |
| Integration | Timesheets app feeds approved hours automatically | 🚧 Planned |
| Integration | Benefits Management app deduction sync | 🚧 Planned |
| Integration | Leave Management paid-leave consumption | 🚧 Planned |
| Integration | Compensation Management pay-change dates | 🚧 Planned |
| Integration | EPMS merit increase processing | 🚧 Planned |
Build scoreboard: ~12 capabilities built, ~44 planned. Treat this app as an early-preview placeholder for a future engine — with a useful admin reporting tool and a read-only AI agent available in the meantime.
What is the Payroll Processing App?
Payroll Processing is positioned as the in-house payroll engine inside MangoApps — the alternative to integrating with an external provider. When complete, it will consume approved timesheets from the Timesheets app, calculate gross pay, apply deductions, withhold federal and state taxes, and distribute payments via ACH direct deposit, printed check, or pay card — all inside MangoApps.
Today the app is an early-preview container that exposes:
- Admin Payroll Reports — a working reporting tool that pulls approved hours from the Timesheets data and generates downloadable reports in CSV, PDF, or JSON. This is what admins use for handing off to an external payroll processor, reconciling labor costs, or auditing hours. It lives at
/admin/business/:id/payroll. - Pay Period Settings — configure weekly, biweekly, semi-monthly, or monthly pay periods with a reference start date and a pay-day offset. These settings drive report date ranges and the pay schedule surfaced to employees.
- Payroll AI Agent — a read-only Ask AI agent that lets employees ask about pay stubs, deductions, tax documents, pay schedule, and year-to-date totals in natural language. Source data today comes from Payroll Connect paychecks (
PayrollConnectPaycheck), not an in-house payroll engine.
Core value proposition (when complete):
- 🏛 System of Record — MangoApps is your payroll system, not a connector to one
- 💵 Gross-to-Net — Calculate withholdings, deductions, and net pay inside the platform
- 🗺 Multi-State Compliance — Federal, state, and local tax handling for distributed workforces
- 🏦 Payment Distribution — Direct deposit, check, or pay card from a single run
- 📄 Year-End Filings — W-2, 1099, Form 941, Form 940 generation and e-filing
How It Works (Today vs. Planned)
Today — Reporting and Self-Service (Built)
┌─────────────────────────────────────────────────────────────────────────┐
│ TODAY'S PAYROLL SURFACE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ TIMESHEETS │───────▶│ APPROVED │───────▶│ PAYROLL │ │
│ │ APP │ │ HOURS │ │ REPORT │ │
│ └─────────────┘ └─────────────┘ └──────┬──────┘ │
│ │ │
│ ┌─────────────────────────┼───────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌────────┐ ┌────┐ │
│ │ CSV │ │ PDF │ │JSON│ │
│ └────┬────┘ └───┬────┘ └──┬─┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────┐ │
│ │ Handed to external payroll provider │ │
│ │ (ADP / Gusto / Paychex / Workday / etc.) │ │
│ │ or reconciled via Payroll Connect │ │
│ └──────────────────────────────────────────┘ │
│ │
│ ┌─────────────┐ │
│ │ Ask AI │───▶ Payroll AI Agent (read-only) │
│ │ sidebar │ ├─ get_my_pay_stubs │
│ └─────────────┘ ├─ get_my_deductions │
│ ├─ get_tax_documents │
│ ├─ get_ytd_pay_summary │
│ └─ compare_pay_stubs │
│ (Source: Payroll Connect paychecks) │
└───────────────────────────────────────────────────────────────────────┘
Planned — Full In-House Engine (Roadmap)
┌──────────────────────────────────────────────────────────────────────────┐
│ PLANNED END-TO-END PAYROLL RUN │
├──────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ TIMESHEETS │ │ BENEFITS │ │ LEAVE │ │COMPENSATION│ │
│ │ (hours) │ │(deductions)│ │ (balances) │ │ (rates) │ │
│ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ GROSS PAY CALCULATION │ │
│ │ Regular + OT + Premium + Bonus + Commission + Retro │ │
│ └──────────────────────────┬─────────────────────────────────┘ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ DEDUCTIONS & CONTRIBUTIONS │ │
│ │ 401(k), HSA, FSA, garnishments, custom, employer match │ │
│ └──────────────────────────┬─────────────────────────────────┘ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ FEDERAL + STATE + LOCAL TAX WITHHOLDING │ │
│ │ IRS Pub 15-T • FICA • FUTA • SUTA • 50 states • locals │ │
│ └──────────────────────────┬─────────────────────────────────┘ │
│ ▼ │
│ ┌────────────┐ │
│ │ PREVIEW │ (gross-to-net breakdown) │
│ │ + DUAL │ │
│ │ SIGN-OFF │ │
│ └─────┬──────┘ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ PAYMENT DISTRIBUTION │ │
│ │ ACH direct deposit • Check • Pay card • Digital stubs │ │
│ └──────────────────────────┬─────────────────────────────────┘ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────┐ │
│ │ YEAR-END COMPLIANCE │ │
│ │ W-2 • 1099 • Form 941 • Form 940 • State filings │ │
│ └────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
Roadmap Timeline (indicative)
Early Preview Planned Modules Target State
───────────── ───────────── ────────────
2026 ─┬────────────────────────────────────────────────────────────────────┐
│ TODAY │
│ ▪ Payroll Reports (CSV/PDF/JSON) │
│ ▪ Pay-period settings │
│ ▪ Payroll AI Agent (read-only, reads Payroll Connect data) │
│ ▪ Employee paycheck self-service (via Payroll Connect) │
├────────────────────────────────────────────────────────────────────┤
│ NEXT │
│ 🚧 Gross pay engine (hourly, salary, OT, bonus, retro) │
│ 🚧 Deductions engine (pre-tax, post-tax, garnishments) │
│ 🚧 Benefits Management deduction sync │
├────────────────────────────────────────────────────────────────────┤
│ THEN │
│ 🚧 Federal + FICA + FUTA withholding │
│ 🚧 State tax (50 states) + SUTA │
│ 🚧 Local tax + multi-state allocation │
│ 🚧 Payroll-run preview + dual approval │
├────────────────────────────────────────────────────────────────────┤
│ LATER │
│ 🚧 ACH direct deposit + check + pay card │
│ 🚧 Year-end filings: W-2, 1099, Form 941, Form 940 │
│ 🚧 GL journal export (QuickBooks, NetSuite, CSV) │
│ 🚧 Leave + Compensation + EPMS tight integration │
└────────────────────────────────────────────────────────────────────┘
Ordering is indicative only. Specific availability dates are announced as modules ship. Businesses that need payroll today should use Payroll Connect.
Current Features (Built)
📊 Payroll Reports
The primary built feature. Admins generate period-scoped reports of hours and pay pulled from approved Timesheets data.
| Feature | Description |
|---|---|
| Date range | Any start/end date; defaults to the current pay period from settings |
| Location filter | Scope a report to one or more locations |
| Department filter | Limit to specific departments |
| User filter | Limit to specific employees |
| Include inactive | Toggle to include terminated employees who worked in the period |
| Leave balances | Optional inclusion of leave balances alongside hours |
| Rest violations | Optional inclusion of rest-period violation flags |
| Formats | CSV, PDF, or JSON |
| Regenerate | Re-run a report after timesheet corrections |
| Email on ready | PayrollMailer.report_ready notifies the creator |
Line items per report (PayrollReportItem):
- Regular hours / overtime hours / total hours
- Regular pay / overtime pay / premium pay / total pay
- One row per employee in the scoped period
How it’s used: Admins hand the CSV or PDF to their external payroll provider (ADP, Gusto, Paychex, Workday) — or to an accountant — to actually cut checks. Payroll Processing does not cut checks today; the report is the deliverable.
Access control (require_admin_manager_or_payroll_permission):
- Admins and super admins see all reports for the business
- Managers and custom-role users see only reports they created, or reports scoped to locations they have
view:payrollpermission on (viaIntegratedPermissionService#accessible_locations_for) - Non-admins cannot include locations in a new report that they don’t have access to
⚙️ Pay Period Settings
Configure how pay periods are structured for the business. Drives the report date-range defaults and the pay schedule returned to employees via the AI agent.
| Setting | Options |
|---|---|
| Pay period type | Weekly, Biweekly, Semi-monthly, Monthly |
| Pay period start day | Day-of-week anchor for weekly/biweekly |
| Pay period dates | Custom dates for semi-monthly / monthly |
| Pay day offset | Days after period end that pay is issued |
| Include pending leave | Whether pending leave affects current period totals |
| Reference start date | Anchor used to compute current and next periods |
Audit trail: Every change is logged via PaperTrail with the reason “Pay period settings updated by admin”.
Location: Admin → General Settings → Payroll Settings (older URL /admin/businesses/:id/payroll/settings 301-redirects here).
🤖 Payroll AI Agent
Read-only Ask AI agent available to employees when Timesheets is enabled and pay amounts are not hidden.
# Gating (from PayrollAgent.enabled_for_business?)
business.timesheets_enabled? &&
!business.business_pay_period_setting&.hide_pay_amounts?
Eight tools (all read-only; RISKY_TOOLS is empty):
| Tool | Purpose |
|---|---|
get_my_pay_stubs |
List recent pay stubs with date, period, gross, net |
get_pay_stub_details |
Full breakdown of one stub (federal, state, FICA, Medicare, deductions, hours) |
get_my_deductions |
Current deductions from the latest stub + Benefits Management sync |
get_tax_documents |
Available W-2 / 1099 documents for a given year |
get_payment_history |
Up to 26 recent payments, optionally filtered by year |
get_pay_schedule |
Frequency + next 5 pay dates |
get_ytd_pay_summary |
Year-to-date gross, net, taxes, and deductions |
compare_pay_stubs |
Diff two specific stubs, or the latest two automatically |
Important grounding note: The agent currently reads from PayrollConnectPaycheck — paychecks imported from an external provider via Payroll Connect. When the in-house engine ships, the agent is intended to read from native payroll records without changing its tool surface.
Fast path: “compare my last two pay stubs” is recognized as a direct tool call, bypassing the full agentic loop for speed.
🧑💼 Employee Paycheck Self-Service
Employee::PaychecksController at /employee/paychecks lists an employee’s paychecks and shows year-to-date totals per paycheck. Requires Payroll Connect to be enabled today — no standalone in-house paycheck model (Paycheck / PayStub) exists in the codebase.
Roadmap Features (Planned, Not Yet Available)
The marketplace directory lists ~44 planned capabilities across seven categories. Each is marked supported: false, note: 'Planned' in src/lib/marketplace_app_definitions/directory/payroll.rb — they are aspirational, not functional. The full list appears in the Feature Evidence Table above; grouped summary below.
💰 Gross Pay Calculation (6 planned)
Hourly, salary, piece-rate, overtime, premium, bonus, commission, retroactive, back-pay, and multi-rate pay computation from approved timesheets.
🧾 Deductions & Contributions (6 planned)
Pre-tax (401(k), 403(b), HSA, FSA, commuter), post-tax (Roth 401(k)), employer match, garnishments with priority ordering, custom deductions, and Benefits Management auto-sync.
🏛 Tax Withholding & Compliance (8 planned)
Federal (IRS Publication 15-T), FICA, FUTA, state income tax across all 50 states, SUTA, local tax, multi-state work allocation, and W-4 / state equivalent form storage.
🏦 Payment Distribution (6 planned)
ACH direct deposit (same-day/next-day), multi-account split deposits, printed checks with MICR encoding, pay cards, paper pay stubs, and digital pay stubs via self-service.
🔁 Payroll Runs (6 planned)
Scheduled runs, off-cycle/bonus/termination runs, preview with gross-to-net breakdown, dual-approval sign-off, void-and-reissue, and per-run audit logs.
📋 Compliance Reporting (7 planned)
Form 941 quarterly, Form 940 annual, W-2 generation and e-file, 1099-NEC and 1099-MISC, state new-hire reporting, workers’ comp classification, and GL journal export to QuickBooks, NetSuite, or CSV.
🔗 App Integrations (5 planned)
Timesheets (hours in), Benefits Management (deduction sync), Leave Management (PTO balance consumption), Compensation Management (pay-change effective dates), and EPMS (merit increase processing).
Integration Vision (Planned)
┌───────────────────────────┐
│ PAYROLL PROCESSING │
│ (in-house engine) │
└────────────┬──────────────┘
│
┌────────────┬──────────────┬────┴─────┬─────────────┬──────────────┐
▼ ▼ ▼ ▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌────────────┐ ┌────────┐ ┌────────────┐ ┌────────────┐
│ TIME- │ │ BENEFITS │ │ LEAVE │ │ COMP- │ │ EPMS │ │ ASK AI │
│ SHEETS │ │ MGMT │ │ MANAGEMENT │ │ MGMT │ │ (Merit) │ │ (Agent) │
└───┬────┘ └────┬─────┘ └─────┬──────┘ └───┬────┘ └─────┬──────┘ └─────┬──────┘
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
Approved Pre/post- Paid-leave Effective Merit Conversational
hours tax consumption pay-change increase paycheck Q&A
feed run deductions on runs dates processing
Today only the Ask AI arrow is live (and it reads from Payroll Connect, not the in-house engine). All other integrations ship with the planned engine modules.
User Roles & Permissions
| Role | Today’s Capabilities |
|---|---|
| Employee | Ask the AI agent about their own pay stubs / deductions / taxes; view their paychecks via Payroll Connect self-service |
| Manager | All employee capabilities + generate Payroll Reports for reports they created or locations they have view:payroll permission on |
| Payroll-permissioned user | Generate / view Payroll Reports for accessible locations (via view:payroll permission) |
| HR / Admin | Full Payroll Reports access across all locations; configure pay period settings |
| System Admin | App enable/disable in the marketplace; AI agent enablement via agent_enabled config |
Privacy: The AI agent enforces “only show the user their own payroll information” in its system prompt, and tool scopes are user-bound (@user.payroll_connect_paychecks). It will not show another employee’s pay data.
Getting Started
For Admins (available today)
- Confirm Timesheets is enabled — Payroll Reports pull from approved timesheet data
- Navigate to Admin → General Settings → Payroll Settings and configure your pay period (weekly / biweekly / semi-monthly / monthly)
- Go to Admin → Payroll and click New Report to generate your first report
- Choose date range, format (CSV / PDF / JSON), and any location / department / user filters
- Download the report and hand it off to your external payroll provider
For Employees (available today)
- Open Ask AI in the sidebar
- Ask things like:
- “What’s my year-to-date gross pay?”
- “Show me my last pay stub”
- “What deductions are on my paycheck?”
- “When’s my next pay date?”
- “Compare my last two pay stubs”
- View paychecks at My Profile → Paychecks (requires Payroll Connect enabled)
For Admins (when the engine ships)
Detailed setup guides will be published alongside each module as it goes GA. Track this article’s last_updated date and the app directory entry for status.
How This Compares to External Payroll Providers
Payroll Processing, when complete, will overlap significantly with dedicated payroll platforms. The value proposition is consolidation — running payroll inside the same system that already holds your employee records, timesheets, benefits, leave, and performance data, rather than synchronizing to a separate system.
| Platform | Strength | Where Payroll Processing aims to fit |
|---|---|---|
| Gusto | Intuitive UX and modern SMB focus | Payroll Processing targets businesses that want payroll inside their existing employee platform, not a separate SaaS |
| ADP | Compliance depth, enterprise scale, broad ecosystem | Payroll Processing trades ADP’s breadth for integration depth with Timesheets, Benefits, Leave, and EPMS in one app |
| Rippling | Unified HR + IT + finance, global payroll | Closest conceptually — both unify HR and payroll; Rippling is global (160+ countries), Payroll Processing is planned for US-only at launch |
| Paychex | Full-service administration, dedicated support | Payroll Processing is self-service inside MangoApps; Paychex Flex layers on a managed-service tier that is not in scope |
| QuickBooks Payroll | Tight accounting integration | Payroll Processing plans GL journal export to QuickBooks so teams can keep QuickBooks as the book of record |
Honest positioning: Until the engine modules ship, these products are not directly comparable. Use Payroll Connect to integrate with any of these providers today; revisit Payroll Processing when the gross-pay, deductions, tax, and payment modules are generally available.
Frequently Asked Questions
Q: When will Payroll Processing be available?
A: It’s in active development. Most capabilities are planned — specific availability dates are announced as individual modules ship. Businesses that need payroll today should use Payroll Connect to integrate with an existing provider.
Q: How is this different from Payroll Connect?
A: Payroll Processing runs payroll in-house — MangoApps is the system of record, calculates withholdings and deductions, and issues payments directly. Payroll Connect integrates with an external provider (ADP, Gusto, Workday, etc.) that does the processing. Use Payroll Processing to consolidate payroll inside MangoApps; use Payroll Connect to keep your existing payroll system.
Q: Do I need the Timesheets app?
A: For Payroll Reports (today) and for the planned engine: yes. Hours come from approved timesheets. The Payroll AI Agent also requires timesheets_enabled?.
Q: Which states will be supported?
A: All 50 US states plus federal are planned at launch. International payroll is on the longer-term roadmap.
Q: Can I switch from Payroll Connect to Payroll Processing later?
A: Yes. Both apps can be enabled simultaneously during transition. Payroll Connect can be disabled once Payroll Processing is running your active payroll.
Q: Why does the Payroll AI Agent currently pull from Payroll Connect data?
A: Because no in-house payroll records exist yet. The agent was built against PayrollConnectPaycheck so employees can ask about pay today. When the in-house engine ships, the agent is intended to transparently read from the native payroll records.
Q: Was this app removed and re-added?
A: Historically the payroll marketplace app was removed (see migration 20260215001817_remove_payroll_marketplace_app.rb) because Payroll Reports was a core admin feature, not a marketplace app. Payroll Processing is the new directional app — an aspirational in-house engine — distinct from both the old reports-only feature and Payroll Connect.
Related Resources
- Payroll Connect — integrate with ADP, Gusto, Workday, Paychex, BambooHR, or MangoPay (use this today)
- Timesheets — required source of approved hours
- Benefits Management — planned deduction sync source
- Compensation Management — planned pay-change feed
- Leave Management — planned PTO balance consumer
- EPMS — planned merit-increase feed
Payroll Processing is a forward-looking app under active development. Today, use it for admin payroll reports, pay-period settings, and the read-only Payroll AI Agent. For running actual payroll, use Payroll Connect with your existing provider until the in-house engine modules ship.