HRIS-to-Payroll-to-GL Integration Playbook

TL;DR

• Bottom line: Payroll integration is a 5-stage pipeline: employee master sync (HRIS) → payroll calculation → GL journal posting → bank file generation → tax filing. Each stage has different APIs, formats, and timing constraints.
• Key limit: GL posting must complete before financial period close; bank files must hit cutoff times (typically 2-4 PM local time for same-day ACH/BACS/SEPA).
• Watch out for: Earnings/deduction code mapping mismatches between HRIS and payroll provider — #1 cause of payroll integration failures and incorrect GL postings.
• Best for: Organizations running HRIS (Workday, SuccessFactors) with external payroll providers (ADP, Paylocity, Paychex) that need automated GL posting to an ERP.
• Authentication: All major providers use OAuth 2.0; ADP uses client credentials flow, Paylocity uses API key + secret, Paychex uses OAuth 2.0 authorization code flow.

System Profile

This playbook covers the end-to-end integration flow from HRIS systems (Workday HCM, SAP SuccessFactors Employee Central) through payroll providers (ADP, Paylocity, Paychex, or native Workday/SAP payroll) to ERP general ledger posting. It applies to both single-country (US) and multi-country deployments. The playbook assumes a middleware/iPaaS layer (MuleSoft, Workato, Boomi, or custom) orchestrating the flow.

API Surfaces & Capabilities

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits

Authentication

Authentication Gotchas

• ADP OAuth tokens are scoped per company code: multi-company integrations need separate tokens per legal entity. [src2]
• Paylocity API keys are company-specific: a payroll service bureau managing 50 clients needs 50 credential sets. [src3]
• Workday ISU accounts must have security group assignments for every business process involved in payroll — missing a single security group causes silent data omission. [src1]
• SAP SF SAML bearer flow requires the X.509 certificate to match between OAuth client registration and the Identity Provider — certificate rotation breaks integrations if not coordinated. [src4]

Constraints

• GL posting timing: Journal entries must post before period close. For monthly close, payroll-to-GL must complete within 1-2 business days of final payroll run.
• Tax filing deadlines: US federal 941 (quarterly), state SUI (quarterly), W-2 (annual Jan 31). EU varies by country. Missed deadlines = penalties.
• Earnings code mapping is 1-to-many: One HRIS earnings type may map to multiple payroll codes depending on FLSA status, state, and tax jurisdiction.
• Multi-entity GL split: A single payroll run for a multi-entity company must split journal entries by legal entity, cost center, and department.
• Bank file cutoff times are immovable: ACH same-day cutoff ~2:00 PM ET; BACS (UK) requires 3-day advance; SEPA (EU) 1-2 days.
• Retroactive adjustments require reversal + re-posting: Cannot update a posted journal entry; must create reversal + new entry.
• No universal multi-country payroll API standard: Each country has different pay components, tax structures, and statutory deductions.

Integration Pattern Decision Tree

START -- Payroll Integration Architecture
|
+-- What is the HRIS-to-Payroll relationship?
|   +-- Native payroll (Workday Payroll, SAP ECP)
|   |   +-- No integration needed for employee data
|   |   +-- GL posting: Workday = Financial Accounting journal task
|   |   +-- GL posting: SAP ECP = IDoc/posting run to S/4HANA
|   +-- Third-party payroll (ADP, Paylocity, Paychex)
|   |   +-- Employee master sync: HRIS --> Payroll (new hires, terms, comp changes)
|   |   +-- Pay data input: Time --> Payroll (hours, earnings, deductions)
|   |   +-- Payroll results: extract via API for GL posting
|   +-- Global payroll aggregator (CloudPay, Papaya, Deel)
|       +-- Single API for multi-country
|       +-- Aggregator handles in-country providers
|
+-- PAYROLL RESULTS: How to extract?
|   +-- ADP: Payroll Output API (pay statements, check-level detail)
|   +-- Paylocity: PayStatements API (summary + detail)
|   +-- Paychex: Check endpoint (pay component breakdown)
|   +-- All: flat file export (CSV) as fallback
|
+-- GL POSTING: How does payroll reach ERP?
|   +-- Summarized journal (most common): 1 entry per run per entity
|   +-- Detailed journal: 1 line per employee per code (high volume)
|   +-- File-based: CSV/XML import (SAP IDoc, Oracle FBDI, D365 data entities)
|
+-- BANK FILE: Payment to employees
    +-- US: ACH (NACHA) | UK: BACS | EU: SEPA SCT | Other: country-specific

Quick Reference: Integration Flow

Step-by-Step Integration Guide

1. Set up employee master data sync (HRIS → Payroll)

Configure the HRIS to push new hires, terminations, compensation changes, and organizational reassignments to the payroll provider. For ADP, use the Worker v2 API; for Paylocity, use the Employee (v2) endpoint; for native payroll, sync is automatic. [src1, src2, src3]

# Sync new hire from Workday to ADP via iPaaS
import requests

# Get Workday employee data via RaaS
workday_url = "https://{tenant}.workday.com/ccx/service/customreport2/{tenant}/{owner}/{report}?format=json"
employee_data = requests.get(workday_url, headers={"Authorization": f"Bearer {workday_token}"}).json()

# Transform to ADP format and create worker
adp_payload = {"events": [{"data": {"transform": {"worker": {
    "person": {"legalName": {"givenName": employee_data["First_Name"],
                              "familyName1": employee_data["Last_Name"]}},
    "workerDates": {"originalHireDate": employee_data["Hire_Date"]}
}}}}]}
response = requests.post("https://api.adp.com/hr/v2/workers",
    json=adp_payload, headers={"Authorization": f"Bearer {adp_token}"})

Verify: GET /hr/v2/workers/{aoid} → worker status = "Active", hire date matches.

2. Configure earnings and deduction code mapping

Map HRIS compensation elements to payroll provider earnings/deduction codes. Pull available codes from the payroll provider API and build a cross-reference table. [src2, src3]

# Pull Paylocity earnings codes and build mapping
earnings_codes = requests.get(
    f"https://api.paylocity.com/api/v2/companies/{company_id}/earnings",
    headers={"Authorization": f"Bearer {token}"}
).json()

EARNINGS_MAP = {
    "Regular":    {"code": "REG",  "category": "E", "gl_account": "6100-100"},
    "Overtime":   {"code": "OT",   "category": "E", "gl_account": "6100-110"},
    "Bonus":      {"code": "BON",  "category": "E", "gl_account": "6100-200"},
    "FedTax":     {"code": "FIT",  "category": "T", "gl_account": "2200-100"},
    "FICA_SS_EE": {"code": "SS",   "category": "T", "gl_account": "2200-300"},
}

Verify: Every HRIS earnings type has a valid payroll code and GL account mapped.

3. Extract payroll results post-run

After each payroll run completes, extract results via API to build GL journal entries. [src2, src3, src5]

# Extract ADP payroll results for GL posting
payroll_data = requests.get("https://api.adp.com/payroll/v1/payroll-output",
    headers={"Authorization": f"Bearer {adp_token}"},
    params={"payPeriod.endDate": "2026-02-28"}).json()

# Aggregate by GL account for journal entry
gl_entries = {}
for statement in payroll_data.get("payStatements", []):
    for earning in statement.get("earnings", []):
        code = earning["earningCode"]["codeValue"]
        amount = float(earning["amount"]["amountValue"])
        gl_account = EARNINGS_MAP.get(code, {}).get("gl_account", "6100-999")
        key = (gl_account, statement.get("costCenter", "0000"), "D")
        gl_entries[key] = gl_entries.get(key, 0) + amount

Verify: Total debits = total credits. Net pay + taxes + deductions = gross pay.

4. Build and post GL journal entries to ERP

Transform aggregated payroll data into the ERP's journal entry format and post. [src6, src7]

# Post payroll journal to SAP S/4HANA via OData
journal_items = []
for (gl_account, cost_center, dc_indicator), amount in gl_entries.items():
    journal_items.append({
        "CompanyCode": "1000", "GLAccount": gl_account.replace("-", ""),
        "CostCenter": cost_center, "AmountInTransactionCurrency": str(amount),
        "TransactionCurrency": "USD", "DebitCreditCode": dc_indicator,
        "PostingDate": "2026-02-28", "DocumentHeaderText": "Payroll Feb 2026 P2"
    })
response = requests.post(s4_url, json={"JournalEntryItemBasic": journal_items},
    headers={"Authorization": f"Bearer {s4_token}", "X-CSRF-Token": csrf_token})

Verify: GET /JournalEntryItemBasic?$filter=AccountingDocument eq '{doc}' → all lines posted, debits = credits.

5. Validate and reconcile

Run a 3-way reconciliation: payroll provider gross-to-net, GL journal entry totals, and bank file net pay total. [src7]

# 3-way reconciliation check
assert abs(gl_total_debits - gl_total_credits) < 0.01, "GL out of balance"
assert abs(payroll_net - bank_file_total) < 0.01, "Bank file mismatch"
assert abs(payroll_gross - (payroll_net + payroll_taxes + payroll_deductions)) < 0.01, "Gross-to-net mismatch"

Verify: All three assertions pass. Investigate specific discrepancy category if any fail.

Data Mapping

HRIS → Payroll Provider Field Mapping

Payroll Output → GL Account Mapping

Data Type Gotchas

• ADP returns ISO 8601 dates; Paylocity returns MM/DD/YYYY in some endpoints and ISO in others. Always parse defensively. [src2, src3]
• Payroll amounts should carry 2 decimal places minimum. Some providers return amounts as strings, some as floats. Always use Decimal/BigNumber, never floating point arithmetic. [src7]
• Tax jurisdiction codes differ by provider: ADP uses proprietary codes, Paylocity uses FIPS, Paychex uses their own mapping. Build a cross-reference table. [src2, src3, src5]
• Negative amounts (voided checks, retro adjustments, garnishment reversals) must correctly reverse the original GL posting. [src7]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Earnings code mapping drift: Provider adds new codes without notifying integration team; GL posts to catch-all. Fix: Monitor for unmapped codes every payroll run; alert on catch-all account postings. [src6]
• Multi-entity GL split failure: Employee transfers between entities mid-pay-period; mapping expects one entity. Fix: Build entity split logic based on transfer effective date. [src7]
• Retroactive pay double-posting: Retro pay posted to both current and prior period without reversing original. Fix: Implement reversal-and-repost pattern for prior period corrections. [src7]
• Bank file timing failure: ACH file generated but not submitted before cutoff. Fix: Automate submission immediately after generation; build 1-hour buffer; manual wire fallback. [src8]
• Tax jurisdiction mismatch: Remote worker withholding wrong for reciprocity agreements. Fix: Maintain work-state + resident-state mapping; update on relocation. [src8]
• OAuth token expiry mid-extraction: Long-running extraction spans past token lifetime. Fix: Token refresh with 5-min pre-expiry buffer; checkpoint progress for restart. [src2]

Anti-Patterns

Wrong: Post one GL journal entry per employee per pay component

# BAD -- creates thousands of GL lines, overwhelms ERP
for employee in payroll_results:
    for component in employee["pay_components"]:
        post_journal_entry(account=component["gl_account"], amount=component["amount"])
# 1,000 employees x 15 components = 15,000 individual journal entries

Correct: Summarize by GL account + cost center, one journal per run per entity

# GOOD -- aggregates to manageable size, standard practice
journal_lines = {}
for employee in payroll_results:
    for component in employee["pay_components"]:
        key = (component["gl_account"], employee["cost_center"], component["dc"], employee["entity"])
        journal_lines[key] = journal_lines.get(key, 0) + component["amount"]
# 1 journal entry per entity, typically 30-80 lines

Wrong: Hardcode earnings/deduction code mappings

# BAD -- breaks when provider adds/changes codes
def map_earning(code):
    if code == "REG": return "6100"
    if code == "OT": return "6110"
    # New state sick leave code? Not handled. Data lost.

Correct: Configurable mapping table with fallback alerting

# GOOD -- external config, unknown-code alerting
EARNINGS_MAP = json.load(open("earnings_gl_map.json"))
def map_earning(code):
    mapping = EARNINGS_MAP.get(code)
    if not mapping:
        alert_payroll_team(f"Unmapped earnings code: {code}")
        return {"gl_account": "6199-000"}  # Catch-all with alert
    return mapping

Wrong: Post GL journal without pre-validation

# BAD -- posts invalid journal, requires manual reversal
journal = build_journal_from_payroll(payroll_data)
erp_client.post_journal(journal)  # May fail with unbalanced entry

Correct: Validate before posting with dry-run

# GOOD -- catches errors before they hit the ERP
journal = build_journal_from_payroll(payroll_data)
errors = validate_journal(journal)  # Check balance, GL accounts, cost centers
if errors:
    alert_finance_team(errors); log_to_dlq(journal, errors)
else:
    erp_client.post_journal(journal)

Common Pitfalls

• Pay frequency mismatch: HRIS stores annual salary but payroll expects per-period amount. If frequency changes (bi-weekly to semi-monthly), divisor changes from 26 to 24. Fix: Derive per-period amount at sync time using provider's pay frequency code. [src6]
• Sandbox limitations: ADP and Paylocity sandboxes have limited data and different behavior from production. Fix: Request full sandbox refresh; use synthetic data for edge cases. [src2, src3]
• GL posting to wrong fiscal period: Payroll runs Jan 31 but check date is Feb 1. Fix: Use check date (pay date) as GL posting date per your accounting policy. [src7]
• Missing employer tax liability postings: Integration extracts employee-side but omits employer FICA, FUTA, SUI. Fix: Always extract both employee and employer portions. [src7]
• Certificate/credential rotation disrupts production: Payroll runs on strict schedule; expired creds break the pipeline. Fix: Track expiration dates; rotate 30 days early; test in sandbox first. [src1, src4]
• Supplemental payroll runs use different tax rules: Off-cycle payroll (bonuses, termination) uses supplemental flat rate vs. aggregate. Fix: Tag each payroll run with type and apply appropriate GL mapping. [src7]

Diagnostic Commands

# ADP: Test authentication
curl -X POST "https://accounts.adp.com/auth/oauth/v2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET"
# Expected: {"access_token":"...","token_type":"Bearer","expires_in":3600}

# ADP: Get worker list
curl -X GET "https://api.adp.com/hr/v2/workers" \
  -H "Authorization: Bearer {token}"
# Expected: {"workers":[{"associateOID":"..."}]}

# Paylocity: Get earnings codes
curl -X GET "https://api.paylocity.com/api/v2/companies/{companyId}/earnings" \
  -H "Authorization: Bearer {token}"
# Expected: [{"earningsCode":"REG","description":"Regular Pay",...}]

# SAP S/4HANA: Verify GL account exists
curl -X GET "https://{host}/sap/opu/odata/sap/API_JOURNALENTRYITEMBASIC_SRV/A_GLAccountInChartOfAccounts('6100')" \
  -H "Authorization: Bearer {token}"
# Expected: {"d":{"GLAccount":"6100","GLAccountName":"Salary Expense"}}

# Workday: Test RaaS payroll journal report
curl -X GET "https://{tenant}.workday.com/ccx/service/customreport2/{tenant}/{owner}/Payroll_GL_Journal?format=json" \
  -H "Authorization: Bearer {token}"
# Expected: {"Report_Entry":[{"Journal_Line":...}]}

Version History & Compatibility

When to Use / When Not to Use

Cross-System Comparison

Important Caveats

• Multi-country payroll has no universal API: each provider covers different countries with different surfaces. Global aggregators (CloudPay, Papaya, Deel) provide a single API but at the cost of reduced control.
• Payroll data is PII-heavy: every API call transmits SSN, salary, bank details. TLS 1.2+ required; tokens must never be logged. Compliance: SOC 2, GDPR Article 32.
• Earnings/deduction codes change with legislative updates (new state sick leave, new tax categories). Integrations must handle unknown codes gracefully.
• GL posting timing (cash-basis vs. accrual) determines whether you post on payroll run date or check date. Confirm with finance before building.
• Rate limit values are approximate and may differ by contract tier. Always verify against current API documentation and your service agreement.
• Sandbox environments may not reflect production behavior; payroll tax tables in sandbox are often simplified.