Payroll APIs

Payroll APIs

Payroll APIs allow developers to integrate income and employment verification, direct deposit switching, and HR management features into applications. These tools provide standardized access to financial and payroll data across various regional and platform environments [1][2][3][5][8].

Authentication and Base URLs

API access relies on specific base URLs, secret configurations, and custom headers. Truv uses a single base URL of https://prod.truv.com/v1/ for both sandbox and production, determining the environment via the Access Secret prefix (`sandbox-` or `prod-`), and requires `X-Access-Client-Id` and `X-Access-Secret` headers [7]. Merge utilizes the standard base URL https://api.merge.dev/api/hris/v1 with regional endpoints for EU and APAC tenants, using Bearer token authentication alongside an `X-Account-Token` header for linked accounts [8]. Finch endpoints use paths like https://api.tryfinch.com/employer/payment with a Bearer token and a default `Finch-API-Version` of 2020-09-17 [11]. Truv API keys can be rotated via the dashboard by creating a new key, updating code locations, and deleting the old one [7].

Integration and Verification Features

Platforms offer bundled SDK solutions and verification methods for different use cases. Plaid provides Document Income, Payroll Income, and Bank Income verification, where Payroll Income supports approximately 80% of the US workforce including gig workers [5]. Plaid recommends Consumer Report Income for most new customers as an FCRA-compliant solution with ready-made attributes [5]. Pinwheel and Plaid support direct deposit switching, income verification, and employment verification [3][5][9]. Pinwheel features a client and server-side integration model consisting of Link token generation, Pinwheel Link initialization, Account creation, Job execution, and Webhook notifications [9]. Gusto requires commercial, security, and implementation reviews before partners can move from demo environments to production [2]. Finch implements Finch Connect as an embedded authorization flow for system access [6].

Data Management and Rate Limits

Mismatch in data handling exists across different unified APIs and provider endpoints. Merge's Employee object returns all employees by default, but active users can be filtered using the `employment_status` query parameter set to `ACTIVE` [4]. Merge rate limits per Linked Account are set at 100 per minute for Launch, 400 per minute for Professional, and 600 per minute for Enterprise [8]. Finch plan structures dictate support levels, with Pro and Premier customers receiving a dedicated Implementation Engineer, Starter plan users relying on self-guided milestones, and non-contract evaluating users receiving full sandbox and guide access [6]. Finch webhooks require upgrading from legacy Free or Build plans to Starter, Pro, or Premier tiers [13].

Webhooks and Retries

Webhook systems use HTTP POST notifications to alert applications of asynchronous events and data updates. Truv webhooks require endpoints to respond with a 2xx status within 10 seconds, triggering up to 3 retry attempts at 30-second intervals upon failure, and use an `X-WEBHOOK-SIGN` header with an HMAC-SHA256 signature [12]. Finch verifies webhooks via HMAC-SHA256 using a base64-decoded secret on a string formatted as `webhook_id.webhook_timestamp.body`, and retries failed deliveries immediately, after 5 seconds, 5 minutes, 30 minutes, and 2 hours [13]. Plaid retries webhooks for up to 24 hours if an endpoint fails to respond within 10 seconds or returns a non-200 response, requiring applications to maintain idempotency to handle out-of-order or duplicate events [10]. Plaid webhooks are configured via the `/link/token/create` webhook parameter or the Plaid Dashboard [10].

What is not covered

Gaps include specific pricing details for all platforms, exact field schemas for non-Merge endpoints, and comprehensive error code definitions beyond basic timeout and rate limit thresholds.