🧾 Guide to the Payment Data API

The Payment Data API lets you retrieve the payment-level detail of payroll runs: every payment made on a pay date, in a pay period, or funded by a funding, with its wages, employer taxes, additional costs, employee withholdings and deductions, and net payouts, itemized line by line.

It's built for post-payroll reconciliation and reporting. You can use it to tie payroll out to your general ledger, check individual payments against your own records, produce your own payroll reports, or feed an audit.

It sits alongside two related APIs:

  • The Payroll Cost API rolls payroll up into cost segments by cost center. Use it when you want totals to invoice or report by client, job, or project.
  • The Worker Payment History API returns the payments of one worker. Use it to show a worker's own history.
  • The Payment Data API returns every payment in a payroll run, one at a time. Use it when you need the detail behind the totals. It's equivalent to the "Payroll Register" file you'd find in legacy payroll systems.

The concepts are the same across these APIs, so a pay code, a cost center, or a tax label means the same thing in each.


How do I retrieve payment data?

You retrieve the payments for one pay date:

GET https://api.everee.com/integration/v1/payment-data?pay-date=2026-10-16

Typically, you'll retrieve the payment data once per pay date, after payroll for that date has been processed. It contains only payments that have been paid, so it's a record of what happened, not a preview of what's coming.

Or you can retrieve the payments of one pay period, identified by its start and end dates:

GET https://api.everee.com/integration/v1/payment-data?pay-period-start-date=2026-10-05&pay-period-end-date=2026-10-11

Send either pay-date, or both pay-period-start-date and pay-period-end-date. Sending both, or only one of the pay period dates, returns an error. The start date must not be after the end date.

Or you can retrieve the payments funded by one funding, using the fundingId from the Payroll Journal API:

GET https://api.everee.com/integration/v1/payment-data?funding-id=4501

This is how you reconcile the two APIs: the journal of a funding summarizes its payments, and this request returns the payments behind it. Send funding-id on its own, not together with a pay date or pay period. A funding that doesn't exist returns no payments.

A pay period can be paid on more than one pay date, for example when some of its payments are paid later than others, so retrieving a pay period can return payments with different payDate values. Paging, the payment format, and which payments are included work the same either way.

📘

Retrieve a pay date after it has finished processing

Payments appear in the payment data as they're paid. Retrieve a pay date or pay period after its payroll has finished processing, and page through it in one pass, so you get a complete and consistent picture. A payment that is paid while you're paging through a pay date or pay period might not be included in that pass.


How does paging work?

A pay date or pay period can include thousands of payments, so this endpoint is paginated with a cursor rather than the page and size parameters used by many other endpoints. See Pagination for how the two styles compare.

  • limit sets the page size. It defaults to 200 and can be up to 1000.
  • Each response includes hasNextPage, and, when there's more data, a nextCursor.
  • To get the next page, send the same request with after set to that nextCursor. Treat the cursor as an opaque value: pass it back exactly as you received it.
  • Keep going until hasNextPage is false. Pages are in a stable order, so you won't see a payment twice.
{
  "items": [ /* payments */ ],
  "pageSize": 200,
  "hasNextPage": true,
  "hasPreviousPage": false,
  "nextCursor": "MjgyMzAzMTE"
}
GET https://api.everee.com/integration/v1/payment-data?pay-date=2026-10-16&after=MjgyMzAzMTE

Paging only moves forward, and responses don't include a total count. If you need the number of payments, count them as you page.


What does a payment look like?

Each item in items is one payment to one worker. Here's an example:

{
  "id": "28230311",
  "workerId": "94cae9c4-a52c-4731-969f-83540f45c2e2",
  "externalWorkerId": "emp-1042",
  "payPeriodStartDate": "2026-10-05",
  "payPeriodEndDate": "2026-10-11",
  "payDate": "2026-10-16",
  "status": "PAID",
  "fundingId": "4501",
  "totalTaxableWages": { "amount": "1200.00", "currency": "USD" },
  "totalNonTaxablePay": { "amount": "0.00", "currency": "USD" },
  "totalEmployerTax": { "amount": "99.00", "currency": "USD" },
  "totalEmployerAdditionalCosts": { "amount": "25.00", "currency": "USD" },
  "totalNetPay": { "amount": "835.00", "currency": "USD" },
  "taxableWages": [
    {
      "payCode": "REGULAR_HOURLY",
      "amount": { "amount": "1050.00", "currency": "USD" },
      "costCenters": [
        { "type": "glCode", "value": "80029" },
        { "type": "clientId", "value": "290" }
      ]
    },
    {
      "payCode": "BONUS",
      "amount": { "amount": "150.00", "currency": "USD" },
      "costCenters": [{ "type": "glCode", "value": "80029" }]
    }
  ],
  "nonTaxablePay": [],
  "employerTaxes": [
    { "name": "Social Security (ER)", "amount": { "amount": "74.40", "currency": "USD" }, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": null },
    { "name": "Medicare (ER)", "amount": { "amount": "17.40", "currency": "USD" }, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": null },
    { "name": "FUTA (ER)", "amount": { "amount": "7.20", "currency": "USD" }, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": null }
  ],
  "employerAdditionalCosts": [
    {
      "name": "Workers' Compensation",
      "amount": { "amount": "25.00", "currency": "USD" },
      "workersCompState": "UT",
      "workersCompClassCode": "64229",
      "workersCompEmployerRate": { "amount": "1.0294", "currency": "USD" }
    }
  ],
  "employeeTaxWithholdings": [
    { "name": "Federal Income Tax", "amountWithheld": { "amount": "132.00", "currency": "USD" }, "resident": null, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": null },
    { "name": "Social Security", "amountWithheld": { "amount": "74.40", "currency": "USD" }, "resident": null, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": null },
    { "name": "Medicare", "amountWithheld": { "amount": "17.40", "currency": "USD" }, "resident": null, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": null },
    { "name": "Utah State Tax", "amountWithheld": { "amount": "54.00", "currency": "USD" }, "resident": true, "subjectWages": { "amount": "1200.00", "currency": "USD" }, "state": "UT" }
  ],
  "employeeDeductions": [
    { "name": "401(k)", "amountDeducted": { "amount": "43.60", "currency": "USD" } },
    {
      "name": "Child Support & Alimony",
      "amountDeducted": { "amount": "43.60", "currency": "USD" },
      "garnishmentOrderCaseId": "2024-DR-004512",
      "garnishmentAgencyName": "Utah Office of Recovery Services",
      "garnishmentAgencyFullAddress": "515 E 100 S, Salt Lake City, UT 84102",
      "garnishmentRemittanceId": "123"
    }
  ],
  "netPayouts": [
    {
      "id": "48213377",
      "type": "DIRECT_DEPOSIT",
      "date": "2026-10-16",
      "netAmount": { "amount": "600.00", "currency": "USD" },
      "status": "PAID",
      "directDepositInfo": { "nickname": "Checking", "routingNumber": "121140399", "accountLast4": "4431", "traceNumber": "12345" }
    },
    {
      "id": "48213378",
      "type": "DIRECT_DEPOSIT",
      "date": "2026-10-16",
      "netAmount": { "amount": "235.00", "currency": "USD" },
      "status": "PAID",
      "directDepositInfo": { "nickname": "Savings", "routingNumber": "121140399", "accountLast4": "7782", "traceNumber": "12346" }
    }
  ]
}

A few things to know about the payment itself:

  • id is the payment's identifier. It's also what you'd use to retrieve the payment from the Worker Payment History API.
  • workerId is Everee's identifier for the worker. externalWorkerId is the worker ID you set yourself, or null if you haven't.
  • payPeriodStartDate and payPeriodEndDate are the dates of the pay period the payment was calculated for, and payDate is when it was paid.
  • fundingId is the funding that funded the payment. It's the same ID as the fundingId in the Payroll Journal API, so you can tie a payment to the journal of its funding. It's null if the payment hasn't been funded through a funding.
  • All monetary amounts are objects with an amount, a decimal string such as 100.00, and an ISO 4217 currency code.

Totals always equal their lines. Each total… property is the sum of the list next to it: totalTaxableWages is the sum of taxableWages, totalNonTaxablePay is the sum of nonTaxablePay, totalEmployerTax is the sum of employerTaxes, totalEmployerAdditionalCosts is the sum of employerAdditionalCosts, and totalNetPay is the sum of netPayouts. You can rely on this when you tie payment data out to your own records.


How are wages broken down?

taxableWages lists the payment's gross taxable wages, and nonTaxablePay lists amounts that aren't taxable, like reimbursements. Each line is the total for one pay code: the pay code's API key if the wages are mapped to one of your custom pay codes, or the standard earning type, like REGULAR_HOURLY, if not.

Each line also lists the cost centers the wages are allocated to, in the costCenters property. These are the same cost centers you send with shifts, payable items, and other wage items, and they work the way they do in the Payroll Cost API: type is a cost center type's key, and value is the value you used with it. See the Guide to cost centers for how cost centers are set up.

Wages are grouped by pay code and by their full set of cost centers. If a worker earned regular wages on two different clients in the same pay period, the payment has two REGULAR_HOURLY lines, one for each client. Wages with no cost centers have an empty costCenters list. They're the same wages that appear in the unallocated cost segment of the Payroll Cost API.


How are taxes, additional costs, and deductions reported?

  • employerTaxes lists the employer payroll taxes for the payment, by tax jurisdiction. Each has the tax amount, the subjectWages it was calculated on, and the state it applies to, or null for federal taxes.
  • employerAdditionalCosts lists the employer's non-tax costs: benefit plan contributions, Workers' Comp insurance premiums, and similar. For Workers' Comp, you also get the workersCompState, the workersCompClassCode, and the employer's workersCompEmployerRate. The rate is in dollars per $100 of gross payroll wages, except in Washington, where it's dollars per hour worked. The calculation already accounts for this difference. Rates keep their full decimal precision, like 1.0294.
  • employeeTaxWithholdings lists taxes withheld from the worker's wages. Where it applies, resident tells you whether the worker was a resident of the jurisdiction on the pay date.
  • employeeDeductions lists everything else taken from the worker's wages, including benefit contributions and garnishments. A garnishment line includes the order's case ID, the agency's name and address, and the garnishmentRemittanceId.

Unlike the Payroll Cost API, which allocates employer taxes, additional costs, and similar amounts across cost centers in proportion to wages, this API reports each of these for the whole payment. Only the wage lines carry cost centers.


How do net payouts work?

netPayouts lists the payouts that carried the worker's take-home pay out of the payment. A payment can have more than one payout, for example when a worker splits their pay across two bank accounts.

Each payout has:

  • id, a unique identifier for the payout.
  • type, which is DIRECT_DEPOSIT for a deposit to a bank account. New payout types may be added over time, so your integration should handle values it doesn't recognize.
  • date, the date the payout is made.
  • netAmount, the amount of the payout.
  • status, which is one of PENDING (not yet completed), PAID (completed), or FAILED. New statuses may be added over time too.
  • directDepositInfo, for direct deposits: the account's nickname, the routingNumber, the last four digits of the account number as accountLast4, and the ACH traceNumber.

totalNetPay is the sum of the netAmount of the payment's payouts.


How are benefit plan hours and wages reported?

benefitPlanAccruals lists what the payment contributed to each of the company's benefit plans the worker is in, such as a 401(k), with the plan year's totals as of the payment. Retirement plan providers use these figures to determine eligibility, contributions, and testing.

{
  "planNumber": "401K-001",
  "planName": "Acme 401(k)",
  "planType": "RETIREMENT_401K",
  "planYearStartDate": "2026-01-01",
  "planYearEndDate": "2026-12-31",
  "payment": {
    "hoursWorked": "75.50",
    "hoursOfService": "83.50",
    "planWages": { "amount": "3050.00", "currency": "USD" },
    "totalWages": { "amount": "3050.00", "currency": "USD" },
    "excludedWages": { "amount": "0.00", "currency": "USD" }
  },
  "planYearToDate": {
    "hoursWorked": "1510.00",
    "hoursOfService": "1670.00",
    "planWages": { "amount": "61000.00", "currency": "USD" },
    "totalWages": { "amount": "61000.00", "currency": "USD" },
    "excludedWages": { "amount": "0.00", "currency": "USD" }
  },
  "coveredByBaseline": false
}
  • planNumber is the plan's plan number, the one your recordkeeper knows it by. A worker can be in more than one plan, so the list has one entry per plan.
  • payment is what this payment contributed, and planYearToDate is the plan year's totals up to and including it. A plan year is the company's own, for example July through June, not necessarily the calendar year.
  • hoursWorked and hoursOfService are decimal hours as strings, rounded to two places. hoursOfService includes paid time off that hoursWorked leaves out. Each plan's rules decide what counts, so the same payment can show different figures for two plans.
  • planWages are the wages that count toward the plan, totalWages are all of the worker's wages (reimbursements aren't wages), and excludedWages is the difference.
  • Plan-year-to-date totals are summed before rounding, so they stay accurate even though each payment's hours are shown rounded.

A plan year's totals can start from totals Everee loaded for the worker as of a date, for example the totals from the company's previous provider. Payments dated on or before that date are already inside those totals, so for them coveredByBaseline is true and planYearToDate is null. Their payment figures are still reported. A payment's date here is the date the plan uses to place it in a plan year: its pay date, or the end of its pay period if the plan counts by that. Payments after that date add to the loaded totals.

benefitPlanAccruals is empty when benefit plan accruals aren't turned on for the company, or the worker isn't in a plan that accrues. These figures aren't part of any of the payment's totals.


Which payments are included?

The Payment Data API includes payments that have been paid and that have wages. Payments that are still being calculated, approved, or funded aren't included, because it's a record of completed payroll. When you retrieve a funding, payments that were pulled back aren't included, even though the funding's journal counts them, so the two can differ by those payments.