Pay Components

Verbs supported: POST

POST: Add a single pay component to the worker. This pay component will be used for apply recurring pay components on a workers check based on the frequency specified. Currently this only supports the ability to POST reduction type pay components.

Endpoint	Description
https://api.paychex.com/workers/{workerId}/paycomponents	Add a pay component to a worker that will be a recurring deduction.

Request (Body):

Element Name	Type	Description
componentID	string	The unique identifier of the pay component.
calculationType	string	The type of calculation that will be applied for the pay component . FLAT_DOLLAR_AMOUNT: This is used for a specific dollar amount. PERCENTAGE: This is used for when a Percentage will be used to calculate the amount and will need a calculationBaseId to specify what to apply against. RATE_X_UNITS: This is used for apply the rate against units and will need a calculationBaseId to specify what to apply against. RATE_X_HOURS: This is used for apply the rate against hours and will need a calculationBaseId to specify what to apply against.
calculationBaseId	string	This is required if you are not using a FLAT_DOLLAR_AMOUNT Calculation Type.
value	number	This is used to specify the value that is used against the calculationType.
startDate	date	Date which this pay component will start to be applied during the payruns. This is an optional field that default to current datetime if not provided. This cannot be backdated but can be added to start in the future.
frequency	object	You will define how often the pay component will be applied during the payruns.

Frequency:

You can cross reference the workers payFrequency against the occurrences to determine what values are applicable.

Element Name	Type	Description
applied	string	Currently we only support a BY_PAY_PERIOD value for the API.
occurrence	string	This is how often the pay component will be applied on the pay run. The available values for this will depend on the payFrequency that a worker is paid which can be found on the worker compensations pay standards.
occuranceIntervals	object	These are sub intervals that are used for occurrences that are larger in duration that allow you to define when to apply the pay component. You can reference the payFrequency and occurance to determine what intervals and values applicable.
effectedChecks	string	Which check(s) within the payrun that the paycomponent will be applied to. FIRST_CHECK: The Pay Component will be applied to the first check for the worker within the pay run. This is used for a pay component that only should be applied once like a health insurance deduction. EVERY_CHECK: The Pay Component will be applied to all of the checks for the worker within the pay run. This is used for a pay component that is applied on all check like a retirement deduction.

{
        "componentId": "00H2A1IUJE7MXV6TQ37U",
        "calculationType": "PERCENTAGE",
        "calculationBaseId": "1174507",
        "value": 15,
        "startDate": "2018-01-22T00:00:00Z",
        "frequency": {
                "applied": "BY_PAY_PERIOD",
                "occurrence": "QUARTERLY",
                "occurrenceIntervals": {
                    "interval1": "2",
                    "interval2": "Last"
                },
                "effectedChecks": "EVERY_CHECK"
            }
}

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

Verbs supported: GET

GET: Get all the the Pay Components for a specific worker.

Request:

Element Name	Type	Description
workerId	string	The id assigned to the worker that the requested for.

Response:

Verb	Description
GET	Worker pay components profile.

Endpoint: https://api.paychex.com/workers/{workerId}/paycomponents/{workerComponentId}

Verbs supported: GET, PATCH, & DELETE

GET: Retrieve a specific pay component that a worker has.

PATCH: Update a specific pay component that a worker has.

DELETE: Remove a specific pay component that a worker has.

Request:

Element Name	Type	Description
workerId	string	The id assigned to the worker that workers are being requested for.
workerComponentId	string	The id of a single pay component that a workers has.

******************************************************NEW as of 12/4/2019 ***********************************************

Endpoint: https://api.paychex.com/workers/{workerId}/paycomponents?classificationType={xyz}

Verbs supported: GET

GET: Retrieve a specific pay component that a worker has, by it’s classification type (such as ‘"DEDUCTION")

Request:

Element Name	Type	Description
workerId	string	The id assigned to the worker that workers are being requested for.
classificationType	string	The classification type of a pay component that a worker has. (such as "DEDUCTION", or "REGULAR",)

Endpoint: https://api.paychex.com/workers/{workerId}/paycomponents?name={xyz}

Verbs supported: GET

GET: Retrieve a specific pay component that a worker has, by it’s name (This can be any name of the pay component that client has created)

Request:

Element Name	Type	Description
workerId	string	The id assigned to the worker that workers are being requested for.
name	string	The name of a pay component that a workers has.

Endpoint: https://api.paychex.com/workers/{workerId}/paycomponents?componentid={componentid}

Verbs supported: GET

GET: Retrieve a specific pay component that a worker has, by it’s unique ID

Request:

Element Name	Type	Description
workerId	string	The id assigned to the worker that workers are being requested for.
componentID	string	The unique identifier of the pay component.

Response

Profile: Worker Pay Components

The representational state of a workers pay component.

Element Name	Type	Description
workerComponentId	string	The id of a single pay component that a workers has.
componentID	string	The unique identifier of the pay component.
name	string	Name of the pay component.
calculationType	string	The type of calculation that will be applied for the pay component . FLAT_DOLLAR_AMOUNT: This is used for a specific dollar amount. PERCENTAGE: This is used for when a Percentage will be used to calculate the amount and will need a calculationBaseId to specify what to apply against. RATE_X_UNITS: This is used for apply the rate against units and will need a calculationBaseId to specify what to apply against. RATE_X_HOURS: This is used for apply the rate against hours and will need a calculationBaseId to specify what to apply against.
calculationBaseId	string	This is required if you are not using a FLAT_DOLLAR_AMOUNT Calculation Type.
value	number	This is used to specify the value that is used against the calculationType.
startDate	date	Date which this pay component will start to be applied during the payruns. This is an optional field that default to current datetime if not provided. This cannot be backdated but can be added to start in the future.
effectOnPay	string	What the effect on pay will be (REDUCTION OR ADDITION), currently only reductions are available.
frequency	object	You will define how often the pay component will be applied during the payruns.

{
    "content": [
        {
            "workerComponentId": "970000223656831",
            "componentId": "970000180599325",
            "name": "Deduction - 1",
            "calculationType": "FLAT_DOLLAR_AMOUNT",
            "value": 250.75,
            "startDate": "2018-03-15T00:00:00Z",
            "effectOnPay": "REDUCTION",
            "frequency": {
                "applied": "BY_PAY_PERIOD",
                "occurrence": "QUARTERLY",
                "occurrenceIntervals": {
                    "interval1": "2",
                    "interval2": "Last"
                },
                "effectedChecks": "EVERY_CHECK"
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.paychex.com/workers/00H2A1IUJDOX2AAKG977/paycomponents/970000223656831"
                }
            ]
        },
        {
            "workerComponentId": "970000224745559",
            "componentId": "970000079956947",
            "name": "Deduction - 2",
            "calculationType": "PERCENTAGE",
            "calculationBaseId": "00H2A1IUJE7MXV6TQ37U",
            "value": 5,
            "startDate": "2018-03-01T00:00:00Z",
            "effectOnPay": "REDUCTION",
            "frequency": {
                "applied": "BY_PAY_PERIOD",
                "occurrence": "QUARTERLY",
                "occurrenceIntervals": {
                    "interval1": "1",
                    "interval2": "Last"
                },
                "effectedChecks": "FIRST_CHECK"
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.paychex.com/workers/00H2A1IUJDOX2AAKG977/paycomponents/970000224745559"
                }
            ]
        },
        {
            "workerComponentId": "970000223656812",
            "componentId": "970000180598323",
            "name": "Deduction - 3",
            "calculationType": "RATE_X_UNITS",
            "calculationBaseId": "00H2A1IUJE7MXV6TQ37U",
            "value": 3,
            "startDate": "2018-03-15T00:00:00Z",
            "effectOnPay": "REDUCTION",
            "frequency": {
                "applied": "BY_PAY_PERIOD",
                "occurrence": "EVERY",
                "effectedChecks": "FIRST_CHECK"
            },
            "links": [
                {
                    "rel": "self",
                    "href": "https://api.paychex.com/workers/00H2A1IUJDOX2AAKG977/paycomponents/970000223656812"
                }
            ]
        }
    ],
    "links": [
        {
            "rel": "self",
            "href": "https://api.paychex.com/workers/00H2A1IUJDOX2AAKG977/paycomponents"
        }
    ]
}

Paychex Developer Program

Pay Components

Response

The representational state of a workers pay component.