External Payrolls

The External Payroll API allows the submissions of payrolls into Check's system that were not paid out through Check. The core use case for this API is importing historical payrolls paid out on a company's previous payroll provider, an important input when migrating between payroll providers.

The External Payroll API follows a similar structure to our core Payroll API, with both Payroll Items and Contractor Payments. The External Payroll object is generally simpler, since Check is not actually paying these payrolls out. Unlike the Payroll API, values on the Payroll Item object, like taxes, benefits, and post_tax_deductions are not computed by Check's calculation engine, and instead should be set to record how much in taxes and deductions were paid on the external payroll.

Earnings and reimbursements

The External Payroll API supports a similar earning and reimbursement structure to the core Payroll API. Check's Structuring Earnings guide details how to define earnings in the Payroll API, with the same mechanics applicable here.

Note that since gross pay will have already been calculated on the previous provider, the External Payroll API does not support the use of earning rates, and earning amounts can simply be inputted directly. The External Payroll API can be used with custom earning codes.

Taxes

Because taxes would have already been calculated on the previous provider, External Payroll Items include a writeable taxes array for detailing what taxes each employee paid on the payroll. Defining a tax payment only requires the ID of the tax paid alongside an amount.

Tax payments can only be included for taxes that the company has a tax election for, which is determined by the the company's workplaces. The Company Tax Election API can be used to list and select the necessary tax, which can then be passed to the External Payroll tax object to define the amount paid.

For example, say that New York City tax is applicable to an employer, and an employee paid that tax on an External Payroll. Querying for the companies tax election would result in:

[
    {
        "tax_id": "tax_yjNkKk061BTipYv7G4Ti",
        "description": "New York City Tax",
        "payer": "employee",
        ...
    },
    ...
]

The tax_id field can then be passed to the employee's payroll item tax array to detail how much the employee paid.

{
    ...
    "taxes": [
        {
          "tax": "tax_yjNkKk061BTipYv7G4Ti",
          "amount": "60.00"
        },
        ...
    ]
}

Deductions

Similar to taxes, since benefits and post-tax deductions would have been calculated and paid out on the external payroll, the amounts paid out are defined in the External Payroll Item benefits and post_tax_deductions arrays.

There are two ways of defining external benefit and post-tax deduction amounts.

Association to an existing deduction

When getting a company set up to run payroll by migrating data from a previous provider, a key step is transferring over the active deduction configurations from the previous provider to the Check system to ensure that the deductions continue to occur for employees. Employee will then likely have deductions on previous payrolls associated with these configurations.

If these deduction configurations were configured for employees, then external payroll item deductions can be associated with these configurations by associating their ID in the respective benefits and post_tax_deductions array.

For example, say that an employee has a 401(k) ben_DvWgRANQawvZYQHqDDbE and post-tax deduction ptd_SgI1iILhkDK2U69LIJjp. To define how much was paid out on the external payroll for these deductions, the payroll item object would include:

{
    ...
    "benefits": [
        {
          "id": "ben_DvWgRANQawvZYQHqDDbE",
          "employee_contribution_amount": "200.00",
          "company_contribution_amount": "300.00",
        }
    ],
    "post_tax_deductions": [
      	{
          "id": "ptd_SgI1iILhkDK2U69LIJjp",
          "amount": "100.00",
        }
    ]
}

Automatic creation of external deductions

Deduction amounts can also be defined without attributing them to specific benefit objects. This is particularly useful for historical deductions that were paid out on a previous payroll provider that are no longer active, thus would not be migrated over into the Check system.

To do so, external deductions can simply be defined with the benefit type or deduction description and the amount paid. For example, if an employee was deducted for an external 401(k) and a post-tax deduction for a uniform, the following request can be made:

{
    ...
    "benefits": [
        {
          "benefit": "401k",
          "employee_contribution_amount": "200.00",
          "company_contribution_amount": "300.00",
        }
    ],
    "post_tax_deductions": [
      	{
          "description": "Uniform",
          "amount": "100.00",
        }
    ]
}

This definition will create external benefits and post-tax deductions configuration objects that are by default hidden from list endpoints, are not editable, and will not apply to future payroll. The creation of these external benefits and post-tax deductions will also not trigger webhook events.

📘

Note: Child Support Garnishments

Child-support garnishments cannot be created automatically via external deductions, and must be defined as a pre-existing configuration to record external payments.

Interactions with the Payroll API

Before approving an External Payroll, all external payrolls are hidden from the core Payroll API as they exist in a draft state. Once an External Payroll is approved, this formalizes it within the payroll timeline, and it will surface as an approved non-managed payroll in the Payroll API (e.g. the managed field will be False).