Checks

Verbs supported: POST

EndpointDescription
https://api.paychex.com/workers/{workerId}/checksAdd a check to a worker for an unprocessed pay period.
https://api.paychex.com/companies/{companyId}/checksAdd a check for one or more worker within a company for an available pay period.


Request (Body):

Element NameTypeDescription
workerIdstringThe id assigned to the worker that the requested for. This is not required when using the worker endpoint.
payPeriodIDstringThe id for the unprocessed payperiod.
checkCorrelationIdstringId that you define which is used for error handling/responses. This is not required when sending a single check.
blockAutoDistributionbooleanThis is used optionally for blocking the auto distribution of the earnings on the workers if they are setup for auto distribution.
earningsobjectThe earnings to apply to the check. Each earning needs to define as one of the following:
  • payHours: Will use the default hourly rate defined on the worker to apply the hours against.
  • payHours & payRate: Will allow you to define the monetary rate that the hours will be applied against.
  • payHours & payRateId: Will allow you to define which workers predefined pay rate the hours will be applied against.
  • payUnits: Will use the default hourly rate defined on the worker to apply the units against.
  • payUnits & payRate: Will allow you to define the monetary rate that the units will be applied against.
  • payUnits & payRateId: Will allow you to define which workers predefined pay rate the units will be applied against.
  • payAmount: Will allow you to define straight monetary amount.


Earnings

Element NameTypeDescription
checkComponentIdstringThe unique identifier associated for the pay component on this check.
componentIDstringThe identifier of the pay component to add to the check. An overtime pay component can't be placed on a worker that is OT exempt.
namestringThe name given to the pay component
classificationTypestringThe category that this component falls into.
effectOnPaystringThe effect that the pay component will have on the check amount.
payRatenumberThe rate amount that will be applied for this component. Used in conjunction with Hours or Units.
payRateIdnumberThe rate identifier for the worker’s compensation
payHoursnumberThe number of hours that will be applied for this component. Used in conjunction with rate.
payUnitsnumberThe number of units that will be applied for this component. Used in conjunction with rate.
payAmountnumberThe flat amount to be applied for this component. Not used with Rate, Hours, or Units.
organizationobjectThis is used optionally for assigning an organization to an earning. This option is only available when the client has simple labor distribution (SLD) configured for Payroll. If a client has SLD enabled and an organization is not specified the default org for the worker will be applied. You can check with your Payroll Specialist if your company is setup for SLD.
lineDatedateThis is used optionally for specifying a date that the earning was generated on.
memoedbooleanThis is used optionally for memoing the payHours or payUnits so that they are informational when using a payAmount.
jobIdstringThis is used optionally for overriding a job when it needs to be different then the workers default. This option is only available when the client has job costing.
laborAssignmentIdstringThis is used optionally for overriding a labor assignment when it needs to be different then the workers assignment distribution. This option is only available when the client has labor assignment.

 

[
        {
        "payPeriodId": "1020026427391732",
        "workerId": "004UWBZQJ7GEB9TVWFR9",
        "checkCorrelationId": "yourID_1",
        "blockAutoDistribution": false,
        "earnings": [
                {"componentId":"1020021373899133", "payHours":"4"},
                {"componentId":"1020021373899133", "payHours":"5", "payRate":"22.50"},
                {"componentId":"1020021373899133", "payHours":"6", "payRateId":"1020026420674940"},
                {"componentId":"1020021373899133", "payUnits":"7"},
                {"componentId":"1020021373899133", "payUnits":"8", "payRate":"7.25"},
                {"componentId":"1020021373899133", "payUnits":"9", "payRateId":"1020026420674942"},
                {"componentId":"1020021373899318", "payAmount":"300.60",
                        "organization": {
                        "organizationId": "1020022951957523"
                    }
                }
                ]
        },
        {
        "payPeriodId": "1020026427391732",
        "workerId": "00Z1IQF9J0MIGR3K3VXO",
        "checkCorrelationId": "yourID_2",
        "blockAutoDistribution": true,
        "earnings": [
                {"componentId":"1020021373899318", "payAmount":"250.00"},
                {"componentId":"1020021373899133", "payAmount":"80.00", "payHours":"2", "lineDate":"2018-12-20T00:00:00Z", "memoed": true},
                {"componentId":"1020021373899133", "payAmount":"100", "jobId": "970001557916904"},
                {"componentId":"1020021373899133", "payAmount":"150", "laborAssignmentId": "970001701620720"},
                ]
        }
]

Endpoint: https://api.paychex.com/workers/{workerId}/checks?payperiodid={payPeriodId}

Endpoint: https://api.paychex.com/companies/{companyId}/checks?payperiodid={payPeriodId}

Verbs supported: GET

GET: Get check(s) that are for a specific worker or company within a processed or unprocessed pay period.

Request:

Element NameTypeDescription
workerIdstringThe id assigned to the worker that the requested for.
payPeriodIdstringThe id assigned to the pay period that the the check will be within.

Response:

VerbProfileDescription
GEThttp://api.paychex.com/profiles/payroll/checks/v1Unprocessed checks profile (default profile)
GEThttp://api.paychex.com/profiles/payroll/processedchecks/v1Processed checks profile which will contain amounts calculated during processing.

Endpoint: https://api.paychex.com/workers/{workerId}/checks/{paycheckId}

Verbs supported: GET & DELETE

GET: Retrieve a specific unprocessed or processed check that a worker has.

DELETE: Remove a specific unprocessed check that a worker has.

Request:

Element NameTypeDescription
workerIdstringThe id assigned to the worker that workers are being requested for.
paycheckIdstringThe id of a single check that a workers has.

Response:

VerbProfileDescription
GEThttp://api.paychex.com/profiles/payroll/check/v1Single Un-Processed check profile.
GEThttp://api.paychex.com/profiles/payroll/processedcheck/v1Single Processed check profile.
DELETEhttp://api.paychex.com/profiles/payroll/check/v1GETS any existing checks for the worker within the deleted checks pay period.

Response

Profile: Check

The representational state of check(s) (processed or unprocessed check).
Element NameTypeDescriptionApplicable to Un-ProcessedApplicable to Processed
workerIdstringThe unique identifier associated a worker representation.xx
paycheckIdstringThe identifier used to identify a pay check.xx
payPeriodIdstringThe identifier used to identify a pay period.xx
earningsobjectEarning pay components on the check. This is different between un-processed and processed.xx
deductionsobjectDeduction pay components on the check. x
informationalobjectInformational pay components on the check. x
taxesobjectTaxes applied on the check taxes. x

 


Processed payroll earning, deduction, and informational

Element NameTypeDescription
checkComponentIdstringThe unique identifier associated for the pay component on this check.
componentIDstringThe identifier of the pay component to add to the check. An overtime pay component can't be placed on a worker that is OT exempt.
namestringThe name given to the pay component
classificationTypestringThe category that this component falls into.
effectOnPaystringThe effect that the pay component will have on the check amount.
ratenumberThe rate amount that will be applied for this component. Used in conjunction with Hours or Units.
hoursnumberThe number of hours that will be applied for this component. Used in conjunction with rate.
unitsnumberThe number of units that will be applied for this component. Used in conjunction with rate.
amountnumberThe flat amount to be applied for this component. Not used with Rate, Hours, or Units.
organizationobjectThis is used optionally for assigning an organization to an earning. This option is only available when the client has simple labor distribution (SLD) configured for Payroll. If a client has SLD enabled and an organization is not specified the default org for the worker will be applied. You can check with your Payroll Specialist if your company is setup for SLD.
lineDatedateThis is used optionally for specifying a date that the earning was generated on.
memoedbooleanThis is used optionally for memoing the payHours or payUnits so that they are informational when using a payAmount.
jobIdstringThis is used optionally for overriding a job when it needs to be different then the workers default. This option is only available when the client has job costing.
laborAssignmentIdstringThis is used optionally for overriding a labor assignment when it needs to be different then the workers assignment distribution. This option is only available when the client has labor assignment.


Tax object

.

Element Name

Type

Description

namestringThe name given to the tax.
paidBystringThe payer of the tax amount.
  • EMPLOYEE_WITHHOLDING
  • EMPLOYER_LIABILITY
amountnumberThe final calculated amount for this tax (or partial distribution of the tax).
laborAssignmentIdstringThe identifier of the labor assignment to which the tax (or portion of the tax) is distributed. (applicable only when the client has labor assignments).
jobIdstringThe identifier of the job to which the tax (or portion of the tax) is distributed (applicable only when the client has job costing).
organizationobjectThis is used optionally for assigning an organization to an earning. This option is only available when the client has simple labor distribution (SLD) configured for Payroll. If a client has SLD enabled and an organization is not specified the default org for the worker will be applied. You can check with your Payroll Specialist if your company is setup for SLD.

Un-Processed response

{
    "content": [
        {
            "workerId": "004UWBZQJ7GEB9TVWFR9",
            "paycheckId": "1020026552555444",
            "payPeriodId": "1020026427391732",
            "earnings": [
                {
                    "componentId": "1020021373899133",
                    "checkComponentId": "1020026552555441",
                    "name": "Hourly",
                    "classificationType": "REGULAR",
                    "effectOnPay": "ADDITION",
                    "payRate": "40.2000",
                    "payHours": "4",
                    "organization": {
                        "organizationId": "1020022951957515",
                        "name": " Branch A - East"
                    }
                },
                {
                    "componentId": "1020021373899133",
                    "checkComponentId": "1020026552555445",
                    "name": "Hourly",
                    "classificationType": "REGULAR",
                    "effectOnPay": "ADDITION",
                    "payRate": "7.25",
                    "payUnits": "8",
                    "organization": {
                        "organizationId": "1020022951957515",
                        "name": " Branch A - East"
                    }
                },
                {
                    "componentId": "1020021373899318",
                    "checkComponentId": "1020026552555447",
                    "name": "Bonus",
                    "classificationType": "SUPPLEMENTAL",
                    "effectOnPay": "ADDITION",
                    "payAmount": "300.60",
                    "organization": {
                        "organizationId": "1020022951957523",
                        "name": " Branch B - West"
                    }
                }
            ],
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.paychex.com/workers/004UWBZQJ7GEB9TVWFR9/checks/1020026552555444"
                }
            ]
        },
        {
            "workerId": "00Z1IQF9J0MIGR3K3VXO",
            "paycheckId": "1020026552555462",
            "payPeriodId": "1020026427391732",
            "blockAutoDistribution": true,
            "earnings": [
                {
                    "componentId": "1020021373899318",
                    "checkComponentId": "1020026552555462",
                    "name": "Bonus",
                    "classificationType": "SUPPLEMENTAL",
                    "effectOnPay": "ADDITION",
                    "payAmount": "250.00",
                    "organization": {
                        "organizationId": "1020022951957523",
                        "name": " Branch B - West"
                    }
                }
            ],
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.paychex.com/workers/00Z1IQF9J0MIGR3K3VXO/checks/1020026552555462"
                }
            ]
        }
    ]
}

Processed response

{
    "content": [
        {
            "payPeriodId": "970002146440893",
            "paycheckId": "00H2A1IUJVF8Y2EPA6XD",
            "workerId": "00H2A1IUJKSLXZ07NHIA",
            "checkDate": "2019-05-12T20:00:00Z",
            "netPay": "506.65",
            "checkType": "Regular",
            "checkNumber": "1",
            "earnings": [
                {
                    "componentId": "970000076689381",
                    "checkComponentId": "970002146440900",
                    "name": "Hourly",
                    "classificationType": "Regular",
                    "effectOnPay": "ADDITION",
                    "memoed": false,
                    "laborAssignmentId": "970001557863345",
                    "organization": {
                        "organizationId": "970001701620695",
                        "name": "2 Level 2"
                    },
                    "jobName": "My job 1",
                    "amount": "400.0",
                    "rate": "20",
                    "hours": "20.0"
                },
                {
                    "componentId": "970000076689381",
                    "checkComponentId": "970002146440900",
                    "name": "Hourly",
                    "classificationType": "Regular",
                    "effectOnPay": "ADDITION",
                    "memoed": false,
                    "laborAssignmentId": "970001701620607",
                    "organization": {
                        "organizationId": "970001701620695",
                        "name": "2 Level 2"
                    },
                    "jobName": "My job 2",
                    "amount": "400.0",
                    "rate": "20",
                    "hours": "20.0"
                }
            ],
            "deductions": [
                {
                    "componentId": "970000191960058",
                    "checkComponentId": "970002146440901",
                    "name": "IRA EE",
                    "classificationType": "IRA",
                    "effectOnPay": "REDUCTION",
                    "memoed": false,
                    "laborAssignmentId": "970001557863345",
                    "organization": {
                        "organizationId": "970001701620695",
                        "name": "2 Level 2"
                    },
                    "jobName": "My job 1",
                    "amount": "200.0"
                }
            ],
           "informational": [
                {
                    "componentId": "970000191960058",
                    "checkComponentId": "970002146440999",
                    "name": "Info",
                    "classificationType": "INFORMATIONAL,
                    "effectOnPay": "INFORMATIONAL",
                    "amount": "50.0"
                }
            ],
            "taxes": [
                {
                    "name": "Employee Medicare Tax",
                    "laborAssignmentId": "970001557863345",
                    "jobId": "970001557916904",
                    "paidBy": "EMPLOYEE_WITHHOLDING",
                    "amount": "11.6"
                },
                {
                    "name": "Employee Social Security Tax",
                    "laborAssignmentId": "970001557863345",
                    "jobId": "970001557916904",
                    "paidBy": "EMPLOYEE_WITHHOLDING",
                    "amount": "49.6"
                },
                {
                    "name": "Employer Medicare Tax",
                    "laborAssignmentId": "970001557863345",
                    "jobId": "970001557916904",
                    "paidBy": "EMPLOYER_LIABILITY",
                    "amount": "11.6"
                },
                {
                    "name": "Employer Social Security Tax",
                    "laborAssignmentId": "970001557863345",
                    "jobId": "970001557916904",
                    "paidBy": "EMPLOYER_LIABILITY",
                    "amount": "49.6"
                },
                {
                    "name": "Federal Income Tax",
                    "laborAssignmentId": "970001557863345",
                    "jobId": "970001557916904",
                    "paidBy": "EMPLOYEE_WITHHOLDING",
                    "amount": "28.33"
                },
                {
                    "name": "Federal Unemployment Insurance",
                    "laborAssignmentId": "970001557863345",
                    "jobId": "970001557916904",
                    "paidBy": "EMPLOYER_LIABILITY",
                    "amount": "4.8"
                },
                {
                    "name": "New York Disability Insurance",
                    "laborAssignmentId": "970001557863345",
                    "jobId": "970001557916904",
                    "paidBy": "EMPLOYEE_WITHHOLDING",
                    "amount": "2.6"
                },
                {
                    "name": "New York Income Tax",
                    "laborAssignmentId": "970001557863345",
                    "jobId": "970001557916904",
                    "paidBy": "EMPLOYEE_WITHHOLDING",
                    "amount": "0.0"
                },
                {
                    "name": "New York Paid Family Leave Insurance",
                    "laborAssignmentId": "970001557863345",
                    "jobId": "970001557916904",
                    "paidBy": "EMPLOYEE_WITHHOLDING",
                    "amount": "1.22"
                },
                {
                    "name": "New York Unemployment Insurance",
                    "laborAssignmentId": "970001557863345",
                    "jobId": "970001557916904",
                    "paidBy": "EMPLOYER_LIABILITY",
                    "amount": "25.0"
                },
                {
                    "name": "Re-employment Service Fund",
                    "laborAssignmentId": "970001557863345",
                    "jobId": "970001557916904",
                    "paidBy": "EMPLOYER_LIABILITY",
                    "amount": "0.6"
                }
            ]
        }
    ]
}