Payidi Payroll
Payidi Payroll API

Payroll calculations and paystubs, built into your app.

One API for 2026 federal withholding, all 50 states + DC, local taxes and state programs like SDI and paid leave — plus payroll runs and paystub PDFs that anyone can verify.

Request API accessRead the reference
# Calculate one paycheck — nothing is saved
curl -X POST $BASE/api/v1/calculate \
  -H "Authorization: Bearer pk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "payType": "hourly", "payRate": 22,
        "payFrequency": "biweekly",
        "regularHours": 80, "overtimeHours": 4,
        "workState": "CA", "payDate": "2026-11-13",
        "taxProfile": { "filingStatus": "single" } }'

# → gross, federal, state, SS, Medicare, CA SDI,
#   net pay and employer taxes

How it works

Every business that runs payroll through the API is verified first, so paystubs always carry a real, checked employer name.

Get your keys

Request access below. Once approved, we email a free test key and a live key.

Register a company

POST /companies with legal name, EIN and address. It starts as pending.

We verify it

We check the IRS EIN letter, Secretary of State record and owner ID. Then payroll unlocks.

Run payroll

Add employees, create a run, approve it, and download paystub PDFs.

What you get

Taxes are always calculated by Payidi — callers can't type in tax amounts or year-to-date totals.

All 50 states + DC

2026 IRS Pub 15-T federal withholding, Social Security wage base and Additional Medicare, every state's withholding formula, Maryland county tax, flat local taxes, and employee-paid programs (CA SDI, NY PFL, NJ, WA, MA, OR and more).

Payroll runs

Hourly, overtime, double time, salary, bonuses and after-tax deductions. Runs are drafts until approved; approved runs lock and build each employee's year-to-date.

Verifiable paystubs

Payidi-branded PDF earnings statements with the employer's verified name. Every stub has a QR code lenders and landlords can check at payidi.com/verify.

Employer cost

Each check returns the employer's Social Security, Medicare, FUTA and SUTA so you can show total cost of payroll.

Built-in safeguards

Verified employers only, no backdating more than 7 days, pay dates move forward per employee, voiding a run revokes its stubs.

What it doesn't do

The API calculates payroll and issues paystubs. It doesn't move money, pay employees or file tax returns — your business (or ours, on We File plans) handles those.

Test mode & pricing

Build for free with your test key. Pay only when you run real payroll.

Test key — free

Keys starting pk_test_ work right away. Test companies are approved automatically, every calculation is real, and paystubs are stamped SAMPLE and never verify. Test data stays separate from live data.

Live key — platform plan

Keys starting pk_live_ turn on once your monthly platform subscription is set up through our secure Stripe checkout. The plan includes your first 3 verified companies.

Usage

$15 per additional verified company per month, and $3 per employee paid in the month (each person counted once, however many paychecks). Added to your next monthly invoice. The calculator is included.

Your platform plan price is shown at checkout. If a payment fails, live keys keep working for 7 days while you update your card; test keys always work.

Reference

Base URL . Send your key on every request as Authorization: Bearer pk_…. Keep the key on your server — never in a browser or mobile app. JSON in, JSON out. Limit: 120 requests per minute per key.

MethodPathWhat it does
POST/calculateCalculate one paycheck. Nothing is saved.
POST/companiesRegister an employer: legalName, ein (XX-XXXXXXX), address, contactEmail, phone. Starts as pending.
GET/companies · /companies/:idYour companies and their verification status.
PATCH/companies/:idContact info and SUTA rate anytime. Name, EIN, address and logo only before approval.
POST/companies/:id/employeesAdd an employee: name, payType, payRate, payFrequency, workState, taxProfile (federal W-4), stateTax (state form).
GET/companies/:id/employeesList employees.
PATCH/companies/:id/employees/:employeeIdUpdate pay or tax forms, or set status: "terminated".
POST/companies/:id/payroll-runsCreate a draft run: period, pay date and a line per employee (hours, extra earnings, deductions).
GET/companies/:id/payroll-runs · /payroll-runs/:runIdRuns with every line, tax and total.
POST/payroll-runs/:runId/approveLock the run and issue paystubs with verification codes.
POST/payroll-runs/:runId/voidVoid with a reason; its paystubs stop verifying.
DELETE/payroll-runs/:runIdDelete a draft.
GET/payroll-runs/:runId/paystubs · /employees/:employeeId/paystubsPaystub IDs and verification codes.
GET/paystubs/:paystubId/pdfThe earnings statement PDF.
GET/verify/:codePublic: check a paystub's verification code (no key needed).

Example: create and approve a payroll run

# 1. Draft — every check is calculated
curl -X POST $BASE/api/v1/companies/COMPANY_ID/payroll-runs \
  -H "Authorization: Bearer pk_your_key" -H "Content-Type: application/json" \
  -d '{ "payFrequency": "weekly", "periodStart": "2026-11-02", "periodEnd": "2026-11-08",
        "payDate": "2026-11-13",
        "lines": [ { "employeeId": "EMPLOYEE_ID", "regularHours": 40, "overtimeHours": 3.5,
                     "deductions": [ { "description": "Uniform", "amount": 15 } ] } ] }'

# 2. Approve — locks figures, issues paystubs
curl -X POST $BASE/api/v1/payroll-runs/RUN_ID/approve -H "Authorization: Bearer pk_your_key"

# 3. Download a paystub
curl -o stub.pdf $BASE/api/v1/paystubs/PAYSTUB_ID/pdf -H "Authorization: Bearer pk_your_key"

State withholding fields (stateTax)

Copy these from the employee's state withholding form: filingStatus (single, married, married_both_working, married_separate, head_of_household), allowances, additionalAllowances, dependents, extraWithholding, exempt, and localTaxes like [{"name":"Philadelphia Wage Tax","rate":0.0375}]. Some states use extra fields: azRate (AZ), ctCode (CT), njRate (NJ), mdCounty (MD, required), wvTwoEarner (WV), vaAgeBlind (VA), maBlind (MA). New York City and Yonkers resident tax aren't calculated yet. The full state-by-state guide comes with your key.

Errors come back as { "error": "message" } with status 400 (bad input), 401 (key), 402 (live key billing not active), 403 (company not verified), 404, 409 (conflict, e.g. overlapping period), 422 (a case the engine can't calculate, e.g. W-4 Step 2 box) or 429 (rate limit).

Request API access

Tell us about your business and how you'll use payroll. We review requests within one business day and email your test and live keys once approved.