Checkr Pay (v1)

Overview

Checkr Pay is a modern, API-first payouts solution for your flexible workforce. Using the Checkr Pay API, you can:

  • Onboard new workers to your platform (currently only 1099-NEC classified workers are supported)
  • Issue instant payouts to workers (at no cost to your workers)
  • Embed a co-branded Checkr Pay banking experience in your worker app or website (powered by embeddable web components)
  • File tax forms at the end of the year (currently 1099-NEC)

Checkr Pay is run by the team that brought you Checkr - the fastest, easiest, and fairest way to run background checks. Learn more about Checkr here.

Getting Started

This Getting Started Guide is designed to help customers get up-and-running with Checkr Pay, both by providing the necessary context to understand the payment flow, and by giving technical guidance on how to work with the Checkr API. The Checkr Pay API uses resource-oriented URLs, supports HTTPS authentication and HTTPS verbs, and leverages JSON in all responses passed back to customers.

The following sections will walk you through the steps necessary to get started paying workers with the Checkr Pay API:

  1. Create your platform account
  2. Authenticate with Checkr Pay
  3. Onboard a Worker
  4. Send a Payout
  5. File a 1099

Create your platform account

If you would like access to Checkr Pay, please contact our team to request a sandbox account. Our team will review your request and provision a set of sandbox API credentials. Sandbox environment requests are 100% free. Our sandbox does not use real PII or trigger real money movements. Once you are production-ready, please contact us and we will guide you through the onboarding process and enable live requests.

Authenticate with Checkr Pay

Authentication Example
$ curl -X POST https://api.checkrpay.com/customer/v0/payouts \
    -H 'Content-Type: application/json' \
    -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
    -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE' \
    -d '{
      "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
      "metadata": "tx_1313101",
      "description": "$100 payout for a job well done!",
      "amountCents": 10000
    }'

The Checkr Pay team will prodide you with your Access Key and Secret Key.

Your Sandbox and Production accounts will have different keys.

Authenticate your requests by passing your Access ID in the X-CHECKR-PAY-ACCESS-KEY header, and your Secret Key in the X-CHECKR-PAY-SECRET-KEY header.

If you don’t include API credentials when making a request, or if you include incorrect or invalid credentials, Checkr Pay returns a 401 - Unauthorized error. If you include correct credentials, but attempt to access a resource you are not allowed to, Checkr Pay returns a 403 - Forbidden error.

Securing your API Credentials

Best practices for securing your API credentials include:

  1. Don't store your credentials in your codebase or commit it to version control. Instead, make the key securely available only in your production environment. For example, you may choose to store keys in environment variables.
  2. Don't store your API key on the client side. All requests should be made from the server side, and appropriate data should be passed to the client as needed.
  3. If an API key is compromised, Contact Checkr Pay Support to revoke it. The Checkr Pay team will expire the current key and issue you a new set of keys.
  4. Do not use your production API key for testing or development - all testing and development should be performed in the sandbox environment, with your sandbox credentials.

Your API key can be used to make any API call on behalf of your account, such as creating Workers and sending Payouts. In the future, we will support the creation of multiple API keys with varying privileges, enabling you to restrict access based on a least permissions model. However, for today, your API key has unlimited access and must be secured accordingly.

Onboard a Worker

(Optional) Complete a Background Check

First, complete an optional background check for your worker via Checkr. The background check process validates the worker's eligibility to work on your platform (e.g. criminal records, license verification).

If you choose to use a Background Check, you must use a background check package with an SSN pointer Screening included. Typically any criminal search will include an SSN pointer screening. Other screening types do not provide the necessary PII for Checkr Pay to import.
You can initiate and complete a background check programmatically via the [Checkr API](https://docs.checkr.com/#section/Getting-Started).

After completing a background check, the worker can onboard to Checkr Pay with just a single tap - because Checkr Pay securely pulls the worker's PII from their background check profile (with consent).

Onboarding Workers without a Background Check

To onboard workers who have not completed a background check, you can create the worker using the POST /worker endpoint and leave the backgroundCheckId blank. The worker will be asked to enter their PII during onboarding

Create a Worker

Create a Worker
$ curl -X POST https://api.checkrpay.com/customer/v0/workers \
    -H 'Content-Type: application/json' \
    -H 'X-CHECKR-PAY-ACCESS-KEY: CHECKR_PAY_PROD_1000333' \
    -H 'X-CHECKR-PAY-SECRET-KEY: CHECKR_PAY_PROD_83ebeabdec09f6670863766f792ead24d61fe3f9' \
    -d '{
        "metadata": "driver_12345",
        "backgroundCheckId": "e44aa283528e6fde7d542194",
        "profile": {
          "phoneNumber": "+14155552671",
          "email": "john@smith.com"
        }
      }'

After the worker has completed any onboarding steps within your platform, which may include a Checkr background check, onboard them to Checkr Pay by passing the worker's data to the Worker resource.

You can create a worker with just two pieces of information:

  1. Optional: The worker's Candidate ID from a completed Checkr Background Check (to enable Checkr Pay to pull the worker's PII automatically). If you choose to exclude the Background Check, please send this key with a null value.
  2. The worker's contact information (email address, phone number, and mailing address)

Because Checkr Pay is embedded in your worker app or website, it is best practice to provide the same email address and phone number that the worker uses to login to your app/website. That way, the worker will receive Checkr Pay notifications (e.g., 2FA codes) wherever they receive other work-related notifications. Also, that ensures that the email and phone number are valid - preventing login issues down the line.

Remember to replace your API credentials with your API credentials in the cURL example on the right. See Workers for more details on creating workers.

Worker Creation Response

Worker creation response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "metadata": "driver_12345",
  "createdAt": "2022-09-27T20:41:13.680Z",
  "temporaryAuthenticationToken": "dNJDUdffkgn3k209rt73o223of",
  "backgroundCheckId": "e44aa283528e6fde7d542194",
  "profile": {
    "phoneNumber": "+14155552671",
    "email": "john@smith.com",
    "address": {
      "street": "245 E. 73rd Street",
      "street2": null,
      "city": "New York",
      "state": "NY",
      "postalCode": "10021",
      "country": "US"
    }
  },
  "status": "pending"
}

The Checkr Pay API responds immediately with the newly-created Worker object.

Store the ID for this new Worker object. You'll need this to send the worker a Payout later on.

Also note the returned temporaryAuthenticationToken value. You'll use this value to authenticate the worker for account activation via the embeddable component (see below).

Onboard the Worker

Example webhook for an activated Worker
{
  "id": "6400d928a800385b3002d473",
  "object": "event",
  "type": "worker.onboarded",
  "createdAt": "2022-09-27T20:42:13.680Z",
  "data": {
    "object": {
      "id": "7f9877a3-3cfc-4b62-a325-83fbabd532ad",
      "status": "onboarded",
      "backgroundCheckId": "d8aede80eab3714fc90f2b6b",
      "metadata": "meta-data-for-demo",
      "createdAt": "2023-03-02T17:13:12.741Z",
      "object": "worker"
    }
  }
}

Onboard your newly-created Worker by passing the temporaryAuthenticationToken to the embeddable component in your worker app or website. This component guides the worker through a one-tap process to complete the onboarding process (including legal consents).

After onboarding is complete, the worker is brought to the Checkr Pay embedded worker experience. They will see a $0 balance in their wallet until they recieve a payout. Refer to the Embeddables documentation for more information.

If webhooks are enabled, Checkr Pay pushes a status change webhook event to your webhook URL for every Worker state change - including when the worker is onboarded. Refer to the Webhooks documentation for more information.

The temporaryAuthenticationToken is temporary. The returned token can only be used to authenticate the worker into the embeddable Checkr Pay experience once, after which the token expires. The next time the worker opens the embeddable component, re-authenticate the worker by requesting a refreshed authentication token via the Authenticate a worker endpoint.

Send a Payout

Send a Payout
$ curl -X POST https://api.checkrpay.com/customer/v0/payouts \
    -H 'Content-Type: application/json' \
    -H 'X-CHECKR-PAY-ACCESS-KEY: CHECKR_PAY_PROD_1000333' \
    -H 'X-CHECKR-PAY-SECRET-KEY: CHECKR_PAY_PROD_83ebeabdec09f6670863766f792ead24d61fe3f9' \
    -d '{
      "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
      "metadata": "tx_1313101",
      "description": "$100 payout for a job well done!",
      "amountCents": 10000
    }'
Send a Payout response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "metadata": "tx_1313101",
  "description": "$100 payout for a job well done!",
  "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
  "amountCents": 10000,
  "feeCents": 0,
  "status": "pending",
  "createdAt": "2022-09-27T20:41:13.680Z",
  "completedAt": null,
  "canceledAt": null,
  "cancelCode": null
}

After the worker is activated, send them a payout using the Payouts resource.

You can send a payout with just three pieces of information:

  1. The ID of the Worker to receive the payout;
  2. A payout amount (in cents); and
  3. A payout description (to be surfaced to the worker)

Optionally, you can also pass a metadata field with a custom identifier for the Payout. This identifier should be unique across all of your payouts.

Checkr responds immediately with a newly-created Payout in the pending status.

Listen For Completed Payout Webhook

Completed Payout webhook
{
  "id": "6400d928a800385b3002d473",
  "object": "event",
  "type": "payout.completed",
  "createdAt": "2022-09-27T20:41:17.680Z",
  "data": {
    "object": {
      "id": "b3883e4b-0100-4243-99f8-9716006d2a13",
      "workerId": "f6eb48d1-8f9c-4934-b8ef-dbafbcf98065",
      "createdAt": "2023-03-02T17:11:55.422Z",
      "amountCents": 250,
      "feeCents": 0,
      "description": "Payout to WorkerId: f6eb48d1-8f9c-4934-b8ef-dbafbcf98065 for 250 cents",
      "status": "completed",
      "object": "payout"
    }
  }
}

After creation, the Payout is processed asynchronously by the Checkr Pay payouts engine (typically within seconds). The payout moves into the completed state, and the worker then has instant access to their funds. The worker is notified of the payout via email or SMS.

If a worker has opted into a Direct Deposit solution, the funds transfer will be initiated within seconds, although funds availability is at the discretion of the receiving bank and may take 2-3 business days.

If webhooks are enabled, Checkr Pay pushes a status change webhook event to your webhook URL for every Payout state change. Refer to the Webhooks documentation for more information.

File a 1099

At the end of the tax year, file a 1099 for the worker as follows.

Important:

This section only applies if your workers are 1099 independent contractors. You must determine whether your workers are 1099 contractors or W-2 employees; Checkr Pay cannnot provide tax or legal advice.

If your workers are W-2 employees (rather than 1099 contractors), you can still pay them with Checkr Pay. Your employees will benefit from the full Checkr Pay experience, including instant cash access and financial wellness. However, you'll need to generate W-2 pay statements and tax forms through a different platform. Contact us for recommended W-2 generation partners.

Create a Tax Record

Create a Tax Record
$ curl -X POST https://api.checkrpay.com/customer/v0/tax_records \
    -H 'Content-Type: application/json' \
    -H 'X-CHECKR-PAY-ACCESS-KEY: CHECKR_PAY_PROD_1000333' \
    -H 'X-CHECKR-PAY-SECRET-KEY: CHECKR_PAY_PROD_83ebeabdec09f6670863766f792ead24d61fe3f9' \
    -d '{
      "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
      "taxYear": 2021,
      "taxFormType": "1099-NEC"
    }'
Create a Tax Record response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
  "taxYear": 2020,
  "taxFormType": "1099-NEC",
  "generatedPdf": null,
  "generatedData": null,
  "status": "pending",
  "createdAt": "2022-09-27T20:41:13.680Z",
  "filedAt": null,
  "canceledAt": null,
  "cancelCode": null
}

First, create a TaxRecord with the Create a new TaxRecord endpoint.

You can create a TaxRecord with just three pieces of information:

  1. The ID of the Worker to file a 1099 for;
  2. The tax year to file the 1099 for; and
  3. The type of tax form to file for the worker (currently, the following tax forms are supported: 1099-NEC).
    You will need to determine yourself which type of tax form to file for your worker; Checkr Pay cannot provide tax or legal advice. This endpoint will return a newly-created TaxRecord in the pending state.

Listen For Webhook

TaxRecord Waiting for Approval Webhook
{
  "id": "6400d928a800385b3002d473",
  "object": "event",
  "type": "tax_record.waiting_for_approval",
  "createdAt": "2022-09-27T20:41:13.680Z",
  "data": {
    "object": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
      "taxYear": 2020,
      "taxFormType": "1099-NEC",
      "generatedPdf": "VGhpcyBpcyBhIDEwOTkgUERGIGZvcm0u",
      "generatedData": {
        "void": false,
        "corrected": false,
        "calendarYear": 2020,
        "payerName": "NurseBolt, LLC",
        [...]
      },
      "status": "waitingForApproval",
      "createdAt": "2022-09-27T20:41:13.680Z",
      "filedAt": null,
      "object": "tax_record"
    }
  }
}

The TaxRecord is generated asynchronously by the Checkr Pay tax engine (typically within seconds). Once the TaxRecord has been generated, it is populated with the following data:

  1. A generatedData object containing the values that Checkr Pay generated for each box of the 1099 form;
  2. A generatedPdf field containing the actual 1099 PDF form that will be transmitted to the IRS and worker (represented in Base 64 format)

When you receive this webhook, you can use it to trigger custom business logic (e.g., an internal review flow).

Approve TaxRecord

Approve a Tax Record
$ curl -X PUT https://api.checkrpay.com/customer/v0/tax_records/123e4567-e89b-12d3-a456-426614174000 \
    -H 'Content-Type: application/json' \
    -H 'X-CHECKR-PAY-ACCESS-KEY: CHECKR_PAY_PROD_1000333' \
    -H 'X-CHECKR-PAY-SECRET-KEY: CHECKR_PAY_PROD_83ebeabdec09f6670863766f792ead24d61fe3f9' \
    -d '{
      "status": "approved",
      "taxYear": 2020
    }'
Approve a Tax Record response
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
  "taxYear": 2020,
  "taxFormType": "1099-NEC",
  "generatedPdf": "VGhpcyBpcyBhIDEwOTkgUERGIGZvcm0u",
  "generatedData": {
    "void": false,
    "corrected": false,
    "calendarYear": 2020,
    "payerName": "NurseBolt, LLC",
    [...]
  },
  "status": "approved",
  "createdAt": "2022-09-27T20:41:13.680Z",
  "filedAt": null
}

Once you are ready to file the 1099, you can do so using the Update a TaxRecord endpoint. Call this endpoint with a new status of approved. This endpoint will return an update TaxRecord in the approved state.

Listen For Webhook

TaxRecord Webhook
{
  "id": "6400d928a800385b3002d473",
  "object": "event",
  "type": "tax_record.filed",
  "createdAt": "2022-09-27T20:42:13.680Z",
  "data": {
    "object": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
      "taxYear": 2020,
      "taxFormType": "1099-NEC",
      "generatedPdf": "VGhpcyBpcyBhIDEwOTkgUERGIGZvcm0u",
      "generatedData": {
        "void": false,
        "corrected": false,
        "calendarYear": 2020,
        "payerName": "NurseBolt, LLC",
        [...]
      },
      "status": "filed",
      "createdAt": "2022-09-27T20:41:13.680Z",
      "filedAt": "2022-09-27T20:42:13.680Z",
      "object": "tax_record"
    }
  }
}

The TaxRecord is filed asynchronously by the Checkr Pay tax engine (typically within seconds). Once filing is complete, the TaxRecord is moved to the filed status. This status indicates that:

  1. The 1099 form has been successfully e-filed with the IRS; and
  2. The 1099 form has been transmitted to the worker, and is now available for viewing in the worker's embedded Checkr Pay experience.

The worker also receives an email notification with a link to securely view their 1099 form.

That's It!

Congratulations! You have successfully created and paid your new worker, and satisfied your 1099 filing obligation - with just a few Checkr Pay API calls.

Continue scrolling for more detailed reference documentation for the Checkr Pay API.

Webhooks

Use webhooks to receive updates on objects created with the API and to kick off additional workflows based on these events. Each time an event that you subscribed to occurs, Checkr submits a POST request to the designated webhook URL with information about the event. The request also includes a full copy of the related object (e.g., the Worker object).

To enable webhooks for your account, contact your Checkr Pay Implementation Manager or Solution Architect and provide them with your desired Webhook endpoint.

Attributes

Events are how we let you know when a resource on your account changes (e.g., when a worker is activated, or a payout is created). When a resource is changed, we log an Event object and send you a webhook with a JSON representation of the Event. The table below describes the attributes of an Event.

Parameter Type Description
id string ID of the Event. Unique for every Event.
object string Always set to event. This indicates that the webhook contains an Event object.
type string The type of Event. For example, worker.activated or payout.completed. The possible event types are described in this documentation.
createdAt integer Timestamp for the event, in ISO 8601 format.
data hash The data associated with the event. Typically contains an object of the resource related to the event.

Supported webhook URLs

Checkr Pay can send webhooks to most public-facing web endpoints. Specifically, we can send webhooks to any HTTP(s) URI that meets the following format:

http(s)://(<user>:<password>@)<hostname>/<path>

For example, https://notify.company.com/checkr-pay is a valid webhook URI.

A few guidelines for selecting your webhook endpoint:

  • The endpoint to be reached must be public.
  • HTTP can be used only in the Sandbox environment. Live environment webhooks must be HTTPS.
  • Basic Auth is supported by adding username:password@ in front of the hostname (credentials must be URL encoded)

Responding to webhooks

Your endpoint should respond to webhooks as quickly as possible. To acknowledge receipt of a webhook, your endpoint must return a 2xx HTTP status code. This status code should only indicate receipt of the message, not acknowledgment that it was successfully processed by your system. Any other information returned in the response headers or response body is ignored.

It is best practice to store received webhooks in your database for asynchronous processing. That way, you can return a 2xx HTTP status code to our system immediately - and we won't attempt automatic retries if your system encounters an error. (See Retries).

Webhook logs can be found on the Developer Settings page.

Securing webhooks

For greater security, verify that the requests you receive come from Checkr Pay.

We pass along a hash signature with each request in the header X-Checkr-Pay-Signature. The hash signature is generated with the HMAC algorithm, using your API key as a key and SHA256 digest mode. When you receive a request, you can compute a hash and ensure that the one from Checkr matches.

Example hash signature computation:

echo -n "${request_body}" | openssl dgst -sha256 -hmac "${api_key}"

Retries

If a webhook is not successfully acknowledged with a 2xx HTTP status code, Checkr will automatically retry the webhook every minute for 10 minutes, then every hour for 24 hours. Webhooks failing for more than 7 consecutive days are automatically deleted.

Duplicates and Ordering

While webhooks are helpful for updates, they are not foolproof. In some cases, report updates can be sent in rapid succession based on multiple events within the Checkr Pay environment, and may be "mis-heard". For robust webhook handling, we recommend that you account for the following:

  • Duplicate reports (idempotency)
  • Webhook misses
  • Out-of-order webhooks

As a best practice, Checkr Pay recommends that you build a safety net to account for duplicate and out-of-order webhooks. One option might be to build in a function that aggregatess all Events, and processes only one Event of a given type per object (e.g., one worker.activated event per Worker).

To address missed webhook updates, you may also consider adding a function to send an alert if no update of a given type is sent within a certain number of days. This may indicate that an object has not moved on from an intermediary state (e.g., a worker who dropped out of the onboarding funnel will stay in the pending status).

Worker events

Example webhook for an activated Worker
{
  "id": "6400d928a800385b3002d473",
  "object": "event",
  "type": "worker.activated",
  "createdAt": "2022-09-27T20:41:13.680Z",
  "data": {
    "object": {
      "id": "7f9877a3-3cfc-4b62-a325-83fbabd532ad",
      "status": "pending",
      "backgroundCheckId": "d8aede80eab3714fc90f2b6b",
      "metadata": "meta-data-for-demo",
      "createdAt": "2023-03-02T17:13:12.741Z",
      "profile": {
        "legalName": "Mock Candidate",
        "phoneNumber": "+14156566000",
        "email":"example.worker@gmail.com",
        "address": {
          "street": "Example Address Line 1",
          "city": "Example City",
          "state": "CA",
          "postalCode": "94401",
          "country": "US",
          "street2": "Example Address Line 2"
        }
      },
      "object": "worker"
    }
  }
}

Worker events are issued every time a Worker object is updated. For example, when a Worker has completed onboarding, you will receive a worker.onboarded event - signifying that the Worker has completed the necessary onboarding steps and is now ready to receive payouts.

The following events can be issued during the lifecycle of a single Worker:

Event Description
worker.created A new Worker has been created.
worker.manual_review An exception has been raised requiring manual review of the Worker. The Worker will be cleared from this state within 2 business hours.
worker.onboarded A Worker has been onboarded (a worker completed onboarding forms but has not yet completed the banking Know Your Customer(KYC) process).
worker.activated A Worker has been activated (a worker has completed the KYC checks and a Checkr Pay account has been opened).
worker.contact_updated A Worker's name, email, phone number, or address has been updated.
worker.denied A Worker has been denied.
worker.updated A Worker has been updated.
worker.pending_closure An account closure has been initiated. The worker's account will be closed in 7 business days.
worker.closed A Worker account has been closed.

Payout events

Example webhook for a completed Payout
{
  "id": "6400d928a800385b3002d473",
  "object": "event",
  "type": "payout.completed",
  "createdAt": "2022-09-27T20:41:16.680Z",
  "data": {
    "object": {
       "id": "b3883e4b-0100-4243-99f8-9716006d2a13",
       "workerId": "f6eb48d1-8f9c-4934-b8ef-dbafbcf98065",
       "createdAt": "2023-03-02T17:11:55.422Z",
       "amountCents": 250,
       "feeCents": 0,
       "description": "Payout to WorkerId: f6eb48d1-8f9c-4934-b8ef-dbafbcf98065 for 250 cents",
       "status": "completed",
       "object": "payout"
    }
  }
}

Payout events are issued every time a Payout object is updated. For example, when a Payout has completed, you will receive a payout.completed event - signifying that the Payout is completed and the funds are available in the worker's account. You can use Payout events to trigger custom workflows, such as internal reconciliation, or custom notifications to workers notifying them a cashout has cleared.

The following events can be issued during the lifecycle of a single Payout:

Event Description
payout.pending A new Payout has been created.
payout.completed A Payout has been completed. The funds are available in the Worker's account.
payout.canceled A Payout has been canceled.
payout.repayment_created A repayment for the payout was created.

TaxRecord events

Example webhook for a filed TaxRecord
{
  "id": "6400d928a800385b3002d473",
  "object": "event",
  "type": "tax_record.filed",
  "createdAt": "2022-09-27T20:42:14.680Z",
  "data": {
    "object": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
      "taxYear": 2020,
      "taxFormType": "1099-NEC",
      "generatedPdf": "VGhpcyBpcyBhIDEwOTkgUERGIGZvcm0u",
      "generatedData": {
        "void": false,
        "corrected": false,
        "calendarYear": 2020,
        "payerName": "NurseBolt, LLC",
        "payerAddress": {
          "street": "1 Montgomery Street Suite 1234",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94104"
        },
        "recipientTinRedacted": "xxx-xx-1234",
        "recipientName": "Jenny Terry Smith",
        "recipientAddress": {
          "street": "437 Lytton",
          "city": "Palo Alto",
          "state": "CA",
          "zip": "94301"
        },
        "recipientAccountNumber": null,
        "boxOneCents": 1000,
        "boxTwo": false,
        "boxFourCents": 1000,
        "boxFive": null,
        "boxSix": null,
        "boxSeven": null
      },
      "status": "filed",
      "createdAt": "2022-09-27T20:41:13.680Z",
      "object": "tax_record",
    }
  }
}

TaxRecord events are issued every time a TaxRecord object is updated. For example, when a TaxRecord has been filed, you will receive a filed event - signifying that the TaxRecord has been filed with the IRS and transmitted to the Worker. You can use Payout events to trigger custom workflows, such as custom notifications to workers notifying them of their available tax form.

The following events can be issued during the lifecycle of a single TaxRecord:

Event Description
tax_record.pending A new TaxRecord has been created.
tax_record.waiting_for_approval A TaxRecord is waiting for your approval..
tax_record.approved A TaxRecord has been approved and is pending filing.
tax_record.canceled A TaxRecord has been canceled.
tax_record.filed A TaxRecord has been filed with the IRS.

Embeddable

The Checkr Pay Embeddable is a full service neobanking experience that can be embedded directly in your worker app or website - with just a few lines of code.

Your workers can use the Embeddable to access their debit card, view transactions and statements, save for taxes, and more - all without leaving your app or website.

Overview

The Embeddable can be embedded anywhere in your app/website; you are in full control of your branding and UX.

Our team has designed the Embeddable to be striaghtforward and easy to integrate. Features include:

  1. Responsive design. The Embeddable can be adjusted to fit any viewport size that your worker experience supports today.
  2. Customization. The Embeddable can be customized to match your worker experience.
  3. Ease of integration. The Embeddable is a static asset hosted on the Checkr CDN. You can embed it as you would embed any other static web asset (e.g., via an iframe or Webview).
  4. Language/Framework Agnostic. Checkr Pay can be embedded in any web or mobile application, regardless of your tech stack.

We have included an integration checklist below that will get you up-and-running quickly. By following this checklist, you can ship the Checkr Pay Embeddable to your workers with just a few hours of development.

As you complete this checklist, make sure to stay in touch with the Checkr Pay implementations team. We can provide real-time implementation support - including architecture, code review, and code samples. We can also help you customize your embeddable design (including logo, color scheme, and select copy).

Step 1: Create Authentication Endpoint

Example Authentication Endpoint (Express.JS)
import axios from 'axios'; import { Router } from 'express' import { requireActiveSession } from '@/middleware/authentication'
const router = Router()
// The worker must be logged into your application before they can authenticate to Checkr Pay. // Hence, we gate this endpoint behind authentication middleware. // For the purpose of this code sample, we call the middleware requireActiveSession. // However, you are responsible for worker authentication and can implement this however you would like. router.get('/checkr_pay_authenticate', requireActiveSession, (req, res, next) => {
  // Get the Checkr Pay ID for the logged-in user
  const { checkrPayId } = res.locals.user;

  // Generate a TAT and return to the frontend
  const checkrPayApiResponse = await axios.get(
    `https://api-sandbox.checkrpay.com/customer/v0/workers/${checkrPayId}/authenticate`,
    {
      headers: {
        'x-checkr-pay-access-key': process.env.CHECKR_PAY_ACCESS_KEY,
        'x-checkr-pay-secret-key': process.env.CHECKR_PAY_SECRET_KEY
      }
    }
  )
  return res.send({
    token: checkrPayApiResponse.data.temporaryAuthenticationToken
  })
})
export default router

The Checkr Pay Embeddable displays sensitive information to your worker (such as their debit card and earnings details). For security reasons, Checkr Pay needs to authenticate your workers before displaying this information.

With some minor changes to your backend, this experience can be seamless. You can show your workers a personalized Checkr Pay experience, without the need to sign in again. How does this work?

First, the worker signs into your web or mobile application with your existing authentication flow. This step is controlled entirely by you, independent of Checkr Pay.

Once a worker has logged into your application, the worker is shown a Navigation Element in the frontend to access Checkr Pay (such as a menubar icon). When the worker taps the navigation element, your backend server calls the Authenticate a Worker API endpoint to fetch a one-time session token (a Temporary Authentication Token, or TAT) for the worker. Your frontend then uses the session token to display the Checkr Pay embeddable to the worker. Checkr Pay handles the remaining authentication steps (including a one-time SMS verification code, and dynamic fraud monitoring).

To implement authentication, create an Authentication Endpoint on your backend that completes the above tasks. These tasks are also summarized below, and a sample Express.JS implementation is included in the right-hand side of the screen.

Authentication Endpoint Checklist

  1. Validate that the worker has an active session in your application (i.e., ensure the worker is logged in).
  2. Call the Authenticate a Worker Checkr Pay API, which returns a Temporary Authentication Token.
  3. Return the Temporary Authentication Token to the frontend (which uses it to render the embeddable).
Enhance your Earner's Experience!

When building your authentication flow, Checkr Pay strongly recommends implementing the x-checkr-pay-worker-session-id header. Doing so will significantly improve your earners' experience because they will only be asked to complete 2FA one time during their session.

Authentication Flowchart

The above tasks are also summarized in the flowchart below.

Step 2: Display Checkr Pay Emebddable

Example Checkr Pay Screen (React Native)
function PayScreen() {
  // AuthContext contains any data you need to authenticate requests to your backend.
  // Typically, you will store a session token or other time-limited credential in this context.
  const authContext = useContext(AuthContext);

  // Local state to store your worker's Checkr Pay TAT.
  // PayScreen is responsible for fetching a new TAT from your backend every time it is mounted.
  const [token, setToken] = useState(null);

  useEffect(() => {
      // Fetch a new TAT from your backend every time the component is mounted
      // (not on every render - otherwise, we hit an infinite loop, because calling setToken triggers a re-render!)
      if(!token) {
        axios.get("https://your-backend-server.com/authentication-endpoint", { headers: { 'x-session-token': authContext.state.token } } ).then((result) => {
          // Updating state triggers re-render (which will show webview)
          setToken(result.data.token);
        }).catch((error) => {
          console.log(`Error: ${JSON.stringify(error)}`);
        });
      }
  });

  const styles = StyleSheet.create({
    container: {
      flex: 1,
      height: '100%',
      backgroundColor: '#fff',
      alignItems: 'center',
      justifyContent: 'center',
    },
    webView: {
      width: 380
    }
  });

  // When token is blank, show a loading indicator.
  // When token is populated via the async effect above, show the webview.
  return (
    <SafeAreaView forceInset={{top: 'always'}} style={styles.container}>
      {
        token ?
        <WebView
          style={styles.webView}
          automaticallyAdjustContentInsets={false}
          source={{
            uri: `https://cdn-sandbox.checkrpay.com?tempAuthToken=${token}`
          }}
          // Intercept any URL change, and if that URL differs from the original one,
          // Stop the loading, preventing the page change, and open it in the OS navigator instead
          onNavigationStateChange={async (event) => {
            const uriSubdomain = uri.split('.')[0]
            const navigationUrlSubdomain = event.url.split('.')[0]
            if (navigationUrlSubdomain !== uriSubdomain) {
              webviewRef.stopLoading();
              await Linking.openURL(event.url);
            }
          }}
          onError={(e) => {
            webviewRef.reload()
          }}
        />
        :
          <Text>Loading Pay...</Text>
      }
    </SafeAreaView>
  );
}

Add a screen to your frontend application that displays the Checkr Pay Embeddable to your workers. The Embeddable is a static asset that can be loaded from the Checkr Pay CDN.

You can display the Embeddable just as you would display any other static web asset; for example, you can load an HTML5 Web Component, an Inline iframe, an Android Webview, an iOS Webview, or a React Native Webview.

When you load the embeddable from the Checkr Pay CDN, you'll need to provide a Temporary Authentication Token (TAT) as a URI query parameter. This will personalize the experience for your signed-in worker. The TAT can be obtained from your backend's Authentication Endpoint, implemented in the previous step.

To implement the Checkr Pay embeddable, create an screen on your frontend that performs the above tasks. These tasks are also summarized below, and a sample React Native implementation is included in the right-hand side of the screen.

Code samples are available for many common frameworks and languages, such as Flutter, React Native, Swift, and Kotlin. If you would like a code sample, or have questions about your specific implementation, we're here to help. Contact us at customersupport@checkrpay.com.
Checkr Pay Screen Checklist
  1. Every time the screen is opened, call your backend Authentication Endpoint to request a TAT.

  2. Load the the Embeddable from the Checkr Pay CDN URI. The Sandbox and Production URIs are included below for your reference. Note that the TAT is included as a query parameter.

    • Sandbox: https://cdn-sandbox.checkrpay.com?tempAuthToken=$TempAuthToken

    • Production: https://cdn.checkrpay.com?tempAuthToken=$TempAuthToken

  1. Ensure that the screen has a large enough viewport to accomodate the Checkr Pay experience. Minimum sizes are as follows:

    • Height > 460px

    • Width > 350px

  1. Capture navigation within the webview to links other than checkrpay.com. These links should be opened in the mobile device default browser, rather than the webview. This allows users to navigate to external websites, such as our support helpdesk and bank account link flow.

    • In React Native, use the onNavigationStateChange hook. See the code sample above.

    • In iOS WebKit, use the WKNavigationAction object.

    • In Android, override the shouldOverrideUrlLoading method.

Step 3: Add Navigation Element

Example Checkr Pay Navigation Element (React Native)
import { createSwitchNavigator } from 'react-navigation'; import { createStackNavigator } from 'react-navigation-stack'; import { createBottomTabNavigator } from 'react-navigation-tabs';
function getNavigator() {
  // A sample navigation flow that combines Switch and Stack navigation.
  // The worker can switch between two navigation flows - the loginFlow and the mainFlow.
  // a. The loginFlow is displayed to logged-out workers. This flow allows a worker to navigate between two screens - the SignupScreen (to sign up) and the SigninScreen (to sign in).
  // b. The mainFlow is displayed to logged-in workers. This flow allows a worker to navigate between all of your app screens - such as a home screen, an accept shifts screen, and the PayScreen.
  // On the frontend, each navigation flow is displayed to the worker as a set of buttons. 
  // When the worker taps the Pay button, the frontend displays the PayScreen - as implemented in Step 2 above.
  return createSwitchNavigator({
    loginFlow: createStackNavigator({
      Signup: SignupScreen,
      Signin: SigninScreen
    }),
    mainFlow: createBottomTabNavigator({
      GigBoltHome: GigBoltHomeScreen,
      ViewShifts: ViewShiftsScreen,
      Pay: PayScreen
    })
  }, {
    initialRouteName: 'Signup'
  });
}

Finally, add a navigation element to make your Checkr Pay Screen easily accessible by the worker. For example, you might choose to add a wallet button to your app or website homepage that - when clicked - directs the worker to the Checkr Pay Screen.

You are in full control of where you place your navigation element. Our team can recommend a navigation design that will be intuitive to workers, and we are also happy to provide sample designs upon request. Please contact your implementations team for more information.

Some sample navigation elements are listed below. A sample React Native implementation is also included in the right-hand side of the screen.

Regardless of the element you add, what's important is that your workers can readily access the Checkr Pay Screen - without too many clicks or taps.

  1. Add a "Wallet" icon to the bottom navigation bar of your native app (which "sticks" to every page).
  2. Add a "Dollar Sign" icon to the upper-right corner of your native app (displayed only on the homepage).
  3. Add a "Checkr Pay" tab to the navigation bar of your browser-based web application.

Interacting with the API

The Checkr Pay REST API allows you to interact with Workers, Payouts, and TaxRecords. This section provides basic guidance on interacting with the API.

Base URL and Versioning

All URLs referenced in the documentation have the following base:

  • Production Environment: https://api.checkrpay.com/customer/
  • Sandbox Environment: https://api-sandbox.checkrpay.com/customer/

The Checkr Pay REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported. You must specify an API version in every request to the Checkr Pay API. The version is specified in the first path element after the Base URL. For example, access v0 of the Worker resource as follows: https://api.checkrpay.com/customer/v0/workers. The most recent version of Checkr Pay is v0. When backwards incompatible changes are made to the Checkr Pay API, a new version will always be released.

Content-Type

Example request
$ curl -v -X POST https://api.checkrpay.com/customer/v0/workers \
    -H "Content-Type: application/json" \
    -H 'X-CHECKR-PAY-ACCESS-KEY: CHECKR_PAY_PROD_1000333' \
    -H 'X-CHECKR-PAY-SECRET-KEY: CHECKR_PAY_PROD_83ebeabdec09f6670863766f792ead24d61fe3f9' \
    -d '{"metadata": "driver_12345", "backgroundCheckId": "e44aa283528e6fde7d542194", "profile": {"phoneNumber": "+14155552671", "email": "john@smith.com"}}'

The Content-Type entity header is used to describe the media type of a resource. In requests, a Content-Type header tells the server what type of data is being sent. In responses, it tells the client what type of data the returned content actually is. Our platform accepts and returns data in the application/json format, as is typical for RESTful APIs.

Pagination

Example paginated request
$ curl -X GET https://api.checkrpay.com/customer/v0/payouts?workerId=123e4567-e89b-12d3-a456-426614174000&page=2&per_page=25 \
    -H 'X-CHECKR-PAY-ACCESS-KEY: CHECKR_PAY_PROD_1000333' \
    -H 'X-CHECKR-PAY-SECRET-KEY: CHECKR_PAY_PROD_83ebeabdec09f6670863766f792ead24d61fe3f9' \
Example paginated payload
{
  "data": [
    { "id": "123e4567-e89b-12d3-a456-426614174000", ... },
    { "id": "0348eccf-f673-4482-be77-97d9e93e4f30", ... }
  ],
  "next_href": null,
  "previous_href": "http://api.checkrpay.com/customer/v0/candidates?page=1&per_page=25",
  "count": 27
}

Pagination is enabled for endpoints that return a list of records. There are two parameters that control pagination: page, which specifies the page number to retrieve, and per_page, which indicates how many records each page should contain. The default value of per_page is 50 records.

Parameters Description
page integer
greater than or equal to 1
per_page integer
between 1 and 100

Paginated responses include the following attributes:

Attributes Description
count integer
the total number of items
data array
list of objects
next_href string
URI to fetch the next page of results
object string
"list"
previous_href string
URI to fetch the previous page of results

Rate Limiting

Example rate limiting headers
< X-Ratelimit-Limit: 600
< X-Ratelimit-Remaining: 9
< X-Ratelimit-Reset: 2018-02-02T16:39:00Z

In order to provide a high-quality of service for all customers, our API is rate limited. The current limit is 600 requests per minute across all endpoints. We reserve the right to adjust the rate limit for given endpoints. If the rate limit is exceeded, the API responds with a HTTP 429 "Too Many Requests" status code. The response has a X-Ratelimit-Reset header that tells you when the rate limit count will reset.

Here are the headers related to rate limiting that our API returns for any requests:

Header Description
X-Ratelimit-Limit Number of requests allowed per minute
X-Ratelimit-Remaining Remaining number of requests allowed for the current minute
X-Ratelimit-Reset Time at which the rate limit count resets

Idempotency

Example idempotent worker creation request
$ curl -v -X POST https://api.checkrpay.com/customer/v0/workers \
    -H "Content-Type: application/json" \
    -H 'X-CHECKR-PAY-ACCESS-KEY: CHECKR_PAY_PROD_1000333' \
    -H 'X-CHECKR-PAY-SECRET-KEY: CHECKR_PAY_PROD_83ebeabdec09f6670863766f792ead24d61fe3f9' \
    -H 'Idempotency-Key: 40b23921-c005-4ec7-832a-3ae023dbbc11' \
    -d '{"metadata": "driver_12345", "backgroundCheckId": "e44aa283528e6fde7d542194", "profile": {"phoneNumber": "+14155552671", "email": "john@smith.com"}}'

The Checkr Pay API supports idempotency in POST requests. Use this feature to safely repeat POST requests without accidentally creating the same resources multiple times.

First, provide an Idempotency-Key: <key> header to the POST request. This header value will be used server side to recognize retries of the same request.

The client side must then generate a unique value for every POST request, and re-use the same header value in any subsequent retry attempts. We recommend the use of V4 UUIDs to avoid collisions.

When serving the request with a new idempotency key, the Checkr Pay API will save the response (including status code, headers, body) for the first request if it is successful (2xx status), and return the saved response for later requests with the same idempotency key. Error responses will not be cached.

Note: The idempotency key expires after 24 hours. Retries with an expired idempotency key will be handled as new requests.

Supported Characters

The Checkr Pay API supports alphanumeric character input, as well as accented characters and some punctuation marks.

Corresponding regex character ranges: [a-zA-Z0-9ªµºÀ-ÖØ-öø-ÿ\-'., ]

Supported Accented Characters

ª µ º À Á Â Ã Ä Å Æ
Ç È É Ê Ë Ì Í Î Ï Ð
Ñ Ò Ó Ô { Ö Ø Ù Ú Û
Ü Ý Þ ß à á â ã ä å
æ ç è é ê ë ì í î ï
ð ñ ò ó ô õ ö ø ù ú
û ü ý þ ÿ ' . , -

Errors

The Checkr Pay uses HTTP response codes to represent the result of an API request.

  • 2xx codes indicate success.
  • 4xx codes indicate client-side errors
  • 5xx indicate an internal Checkr Pay error For all error responses (i.e., non-2xx responses), Checkr Pay returns a standard data structure. The data structure is as follows:
Field Description
http_code integer
The HTTP response code
error_code enum
A standard error code representing the general cause of the error.
error_message enum
A human-readable error message representing the general cause of the error.
details array
An array of error details. Only included for input_validation_error responses.
Example error
{
  "http_code": 400,
  "error_code": "input_validation_error",
  "error_message": "Invalid TaxRecord creation request.",
  "details": [
    {
      "key": "workerId",
      "errors": [
        "This worker has a status of pending. You must wait until the worker completes onboarding before creating a tax record."
      ]
    }
  ]
}

You may elect to handle certain error_code values programmatically. The following table includes a list of possible error_code values, along with the content of the details field for each code.

Error Code Description
input_validation_error You provided invalid input data in your API request. You may re-attempt the request with corrected information. (HTTP 400)
resource_not_found You attempted to access a resource that does not exist. (HTTP 404)
unauthorized You provided invalid credentials. (HTTP 401)
forbidden You attempted to access a resource without proper authorization. (HTTP 403)
unexpected_error An unexpected error occurred. Please contact Checkr Pay support for more information. Do not re-attempt the request. (HTTP 500)

When an input_validation_error is returned, the response contains a details field. The field is an array of ErrorDetail objects, where each ErrorDetail represents a specific error in your input data. Each ErrorDetail contains the following fields:

Field Description
key enum
The name of the field that caused the error. This will always be a field that you provided in your input equest.
errors array
An array of strings. Each string contains a human-readable error message explaining why the field was invalid.

Metadata

Many Checkr Pay objects - such as Workers and Payouts - contain a metadata field. You can use this field to provide a custom identifier for the object. For example, you may elect to provide a UUID to link the object with a specific record in your database.

Metadata is always optional, and you can leave a metadata field blank if you so desire. If metadata is provided, it must be unique for all instances of a specific object; every Worker, for example, must have a unique metadata value. However, metadata uniqueness is not enforced across different object types; thus, a Payout may have the same metadata as a Worker.

Metadata can be any value up to 50 charcters long, and can contain any supported characters.

Worker Resets in the Sandbox Environment

During your development efforts in the Sandbox environment, you may realize that you need to reset worker information to continue testing some developments. Inside the Sandbox environment, Checkr Pay has created an All Worker Reset endpoint to reset all workers, and a Worker Reset to reset a single worker's registration to help you accomplish this!

Sending a POST request either of these endpoints will cause the worker's (or all workers') email and phone number information to reset, and will be available to be re-used.

Note that Checkr Pay supports re-use of the Checkr Background Checkr Candidate ID and the SSN. As long as the phone and email address are unique for a given worker, no resets are needed to re-use candidate_id or SSN.

Core Resources

Workers

A Worker represents an individual that receives payouts via the Checkr Pay platform. You can create a new Worker with the Create a New Worker endpoint. Once your worker is active, you can pay the worker instantly with the Create a new Payout endpoint, and file 1099 forms for the worker with the Create a new TaxRecord endpoint.

The lifecycle of a newly-created worker is as follows.

Status Description
pending This state is one of two that may represents a worker that has just been created via the Create a new Worker endpoint.

This is a temporary state, and a worker exits this state once they complete the embeddable onboarding flow. Typically, this happens within 30 seconds. However, if a worker fails to complete the onboarding flow (e.g., because they exited the app), the worker may remain in the pending state indefinitely.
require_pii This state represents a worker that has just been created via the Create a new Worker endpoint, but does not have a comprehensive set of PII needed to complete banking KYC processes.

This is a temporary state, and a worker exits this state once they complete the embeddable onboarding flow. Typically, this happens within 30 seconds. However, if a worker fails to complete the onboarding flow (e.g., because they exited the app), the worker may remain in the pending state indefinitely.
onboarded A worker in this state has successfully completed the embeddable Checkr Pay onboarding flow.
active A worker in this state has successfully completed the embeddable Checkr Pay onboarding flow, recieved a payout, and passed banking Know Your Customer checks. They are now fully active. Workers who are active may have their 1099 forms filed.
manual_review A worker in this state has been flagged for manual review by the Checkr Pay system. <1% of workers enter this state.

No action is required from you when a worker enters this state. Checkr Pay takes care of the entire manual review process, and prompts the worker via the embeddable component for any additional documentation required.
denied A worker in this state has been denied from the Checkr Pay platform. It is rare for a worker to enter this state. If you see a worker in the denied state, contact Checkr Pay Support for more information.
pending_closure A worker in this state has requested that their account be closed. In 7 days, the account will progress to a closed status. You can still file a 1099 for a worker in this state, but you can no longer send them a payout.
closed A worker in this state has had their account closed. A worker enters this state if you request account closure via the Update a Worker endpoint. You can still file a 1099 for a worker in this state, but you can no longer send them a payout.
failed An unhandled event occurred while trying to create this worker. When workers are in this state, you cannot file a 1099 or issue payouts. Generally this requires intervention from the Checkr Pay team to correct the failure.

You receive a webhook for every worker state change. Use this webhook to trigger custom logic on your end. See the Webhooks page for more information.

For a visual representation of the Worker lifecycle - including the actions that you can take for a Worker in each state - see the state diagram below.

Payouts

A Payout represents a payment from you to a Worker. You can create a new Payout via the Create a New Payout endpoint.

The lifecycle of a newly-created Payout is as follows. All Payout state changes are made asynchronously by the Checkr Pay payouts engine. You do not need to request any state changes.

Status Description
pending This state represents a Payout that has just been created via the Create a new Payout endpoint.

The Payout is currently queued for asynchronous processing by the payouts engine. The Payout will be processed by the Checkr Pay payouts engine within 2-3 seconds, at which point the Payout is either completed or queued for manual_review.

No action is required from you for a Payout in this state.
queued This state represents a Payout that has just been created via the Create a new Payout endpoint for workers that have not yet activated their Checkr Pay accounts.

The Payout will be queued for asynchronous processing by the payouts engine, and will be processed as soon as the worker activates their Checkr Pay account by accepting the Legal Consents. After that, the Payout move to a completed status .

No action is required from you for a Payout in this state.
completed This state represents a Payout that is completed. The Payout is fully settled and the worker has access to their funds in Checkr Pay.

Typically, a Payout is completed within 2-3 seconds of creation.
manual_review This state represents a Payout that has been queued for manual review.

The Payout will be reviewed by the Checkr Pay Operations Team within 2-3 business hours. Our Operations team either approves the payout (status => completed) or denies it (status => canceled).

No action is required from you for a Payout in this state; our team handles the end-to-end review process.
canceled This state represents a Payout that we were unable to process. The Payout failed and no funds were transferred.

It is rare for a Payout to enter this state. If you encounter a canceled Payout, contact Checkr Pay Support for assistance.

For a visual representation of the Payout lifecycle - including the actions that you can take for a Payout in each state - see the state diagram below.

TaxRecords

A TaxRecord represents a tax form (such as a 1099-MISC) that you file for a Worker. You can create a new TaxRecord via the Create a New TaxRecord endpoint. The lifecycle of a newly-created TaxRecord is as follows.

Status Description
pending This state represents a TaxRecord that has just been created via the Create a new TaxRecord endpoint.

The TaxRecord is currently queued for asynchronous processing by the tax engine. The TaxRecord will be processed by the Checkr Pay tax engine within 2-3 seconds, at which point the TaxRecord moves out of this state.

No action is required from you for a TaxRecord in this state.
waiting_for_approval This state represents a TaxRecord that has been generated by the tax engine.

The TaxRecord is ready for filing, and is waiting for your approval. Approve the TaxRecord for filing by calling the Update a TaxRecord endpoint.
approved This state represents a TaxRecord that is approved for filing.

The TaxRecord is currently queued for asynchronous filing by the tax engine. The TaxRecord will be filed by the tax engine within 2-3 seconds, at which point the TaxRecord moves out of this state.

No action is required from you for a TaxRecord in this state.
filed This state represents a TaxRecord that has been successfully filed. The TaxRecord is fully filed with the IRS and is available for the worker to view in Checkr Pay.

Typically, a TaxRecord is filed within 2-3 seconds of approval.
canceled This state represents a TaxRecord that is canceled. Refer to the cancelCode for more information. A TaxRecord can be canceled either because you requested cancelation via the Update a TaxRecord endpoint (cancelCode == customer_requested), or because the tax engine encountered an error during filing (cancelCode == other)

It is rare for a TaxRecord to have a cancelCode of other; if you encounter a TaxRecord with this cancelCode, contact Checkr Pay Support.

For a visual representation of the TaxRecord lifecycle - including the actions that you can take for a TaxRecord in each state - see the state diagram below.

Workers

Onboard and manage workers.

Create a new worker

This endpoint is used to onboard a new worker to Checkr Pay. Once created, the worker will receive a Checkr Pay account and debit card. The worker can then receive Payouts via the Create a new Payout endpoint.

Assumptions

  1. Your worker must have completed a background check through the Checkr screenings platform. You will need the worker's Candidate ID from a completed background check to create the worker in Checkr Pay. Checkr Pay securely pulls the worker's PII from their background check - so the worker doesn't need to enter it again.
There are two different IDs that Checkr Core uses when working with background check reports. The candidate_id is the value that Checkr Pay uses to pull in the candidate PII and create a Checkr Pay Worker. If you are pulling a GET /report or listening to Checkr's Report webhooks, make sure that you use the candidate_id.
  1. You must have a valid email address, phone number, and mailing address for the worker. This endpoint assumes that the email address, phone number, and mailing address you provide have already been validated (e.g., during your new worker onboarding flow).

Calling the Endpoint

To create a new worker, call this endpoint with the parameters listed below.

Checkr Pay responds with a newly-created worker in either the pending or require_pii state. The pending state indicates the worker's PII is complete and the worker is ready to complete the activation process. A require_pii state indicates that the worker's object needs some additional PII prior to activation. Workers in require_pii will need to enter additional fields during the activation process. The worker object includes a temporary authentication token. Pass the temporary authentication token to the Checkr Pay embeddable component to display a personalized experience to the worker. This component guides the worker through the Checkr Pay onboarding process, which is typically completed in just a single tap. The worker then moves to the active state.

Rarely, a worker may also move into the manual_review or denied states. For more information, see the Worker Lifecycle.

Authorizations:
Request Body schema: application/json

Post the necessary fields for the API to create a new user.

backgroundCheckId
string

The worker's Checkr Background Check Candidate ID. The worker's KYC data is automatically populated from their background check.

required
object

The worker's profile data. This is provided by the customer and cannot be directly edited by the worker.

metadata
string

Optional customer-provided worker metadata. This field is commonly used to label a Checkr Pay worker record with a custom identification value from your database (e.g, an employee identification number.

Responses

Request samples

curl -i -X POST \
  https://api.checkrpay.com/customer/v0/workers \
  -H 'Content-Type: application/json' \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "metadata": "driver_12345",
    "backgroundCheckId": "e44aa283528e6fde7d542194",
    "profile": {
      "phoneNumber": "+14155552671",
      "email": "john@smith.com",
      "address": {
        "street": "1 Montgomery Street",
        "street2": "St 2400",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94104",
        "country": "US"
      }
    }
  }'

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "metadata": "driver_12345",
  • "createdAt": 1385798567,
  • "temporaryAuthenticationToken": "dNJDUdffkgn3k209rt73o223of",
  • "backgroundCheckId": "e44aa283528e6fde7d542194",
  • "profile": {
    },
  • "status": "pending"
}

Retrieve workers

Retrieve all Worker objects. Filter by created_at date with the created_before and created_after query parameters.

This is a paginated endpoint. See the Pagination documentation for more information.

Authorizations:
query Parameters
metadata
string

Search for a worker with a specific metadata value.

Example: metadata=fd09c9d3-067f-488e-937a-313de48da3e0
created_before
string

Returns workers created before the input date.

Example: created_before=10-30-2022
created_after
string

Returns workers created after the input date.

Example: created_after=10-30-2022

Responses

Request samples

curl -i -X GET \
  'https://api.checkrpay.com/customer/v0/workers?metadata=fd09c9d3-067f-488e-937a-313de48da3e0&created_before=10-30-2022&created_after=10-30-2022' \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list",
  • "next_href": null,
  • "previous_href": null,
  • "count": 2
}

Retrieve a worker

Retrieve a single worker by ID.

Authorizations:
path Parameters
id
required
string

ID of worker to retrieve.

Responses

Request samples

curl -i -X GET \
  https://api.checkrpay.com/customer/v0/workers/:id \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "metadata": "driver_12345",
  • "createdAt": "2022-09-27T20:41:13.680Z",
  • "temporaryAuthenticationToken": "dNJDUdffkgn3k209rt73o223of",
  • "backgroundCheckId": "e44aa283528e6fde7d542194",
  • "profile": {
    },
  • "status": "active"
}

Update a worker

Update a single Worker.

The following fields can be updated at this time. If you attempt to update a field other than the ones listed below, a 400 - Bad Request error returned.

  • metadata
    Update a worker's metadata via this endpoint. Keep in mind that metadata must be unique across all your workers.
Authorizations:
path Parameters
id
required
string

ID of worker to retrieve.

Request Body schema: application/json
metadata
string

Optional customer-provided worker metadata. This field is commonly used to label a Checkr Pay worker record with a custom identification value from your database (e.g, an employee identification number).

Responses

Request samples

curl -i -X PUT \
  https://api.checkrpay.com/customer/v0/workers/:id \
  -H 'Content-Type: application/json' \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "metadata": "string"
  }'

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "metadata": "driver_12345",
  • "createdAt": "2022-09-27T20:41:13.680Z",
  • "temporaryAuthenticationToken": "dNJDUdffkgn3k209rt73o223of",
  • "backgroundCheckId": "e44aa283528e6fde7d542194",
  • "profile": {
    },
  • "status": "pending"
}

Close a worker account

Closes a worker's account. This action is irreversible.

This endpoint immediately disables payouts for the worker, and initiates the account closure process explained below.

If the worker is active, this endpoint immediately moves the worker to the pending_closure state. The worker remains in this state for 7 business days, and they can withdraw their balance during this time. After 7 business days, the worker is placed in the closed state and their account is fully closed.

For non-active workers, there is no waiting period. This endpoint immediately moves the worker to the closed state.

Checkr Pay sends your application a webhook for every Worker state change. See the Webhooks page for more information.

Authorizations:
path Parameters
id
required
string

ID of worker to retrieve.

Responses

Request samples

curl -i -X DELETE \
  https://api.checkrpay.com/customer/v0/workers/:id \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
Example
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "metadata": "driver_12345",
  • "createdAt": "2022-09-27T20:41:13.680Z",
  • "backgroundCheckId": "e44aa283528e6fde7d542194",
  • "profile": {
    },
  • "status": "pending_closure"
}

Authenticate a worker

Generate a new Temporary Authentication Token (TAT) for this worker. The TAT is a one-time session token that you generate when a worker accesses the embeddable component.

This endpoint should be called only after the worker has:

  1. Logged in to your worker portal; and

  2. Requested access to the Checkr Wallet experience (e.g., by clicking on a menubar item).

Once you generate a TAT and display the embeddable to the worker, Checkr Pay displays a personalized, signed-in experience to the worker. To access sensitive information, Checkr Pay prompts the worker to complete a second step of authentication for extra security. This is typically a SMS verification challenge.

TATs are intended for one-time use. You must generate a new TAT every time the worker accesses the embeddable. Otherwise, the worker may see a session expired erorr.

If you call this end point frequently and want to avoid prompting the worker for a second authentication, provide a x-checkr-pay-worker-session-id header which corresponds to the worker's logged in session in your application.

Authorizations:
path Parameters
id
required
string

ID of worker to authenticate.

header Parameters
x-checkr-pay-worker-session-id
string

An id corresponding to the worker's login session from your system. When provided the TAT will be cached for a 12 hour period.

Responses

Request samples

curl -i -X GET \
  https://api.checkrpay.com/customer/v0/workers/:id/authenticate \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE' \
  -H 'x-checkr-pay-worker-session-id: string'

Response samples

Content type
application/json
{
  • "temporaryAuthenticationToken": "dNJDUdffkgn3k209rt73o223of"
}

Reset a specific Sandbox Account Test Worker

This endpoint is only available in the Checkr Pay Sandbox, and is intended only to facilitate testing.

Checkr Pay requires that each worker associated with your account have a unique phone number and email address.

Calling this endpoint will reset registration data associated with the specific worker identified in the URL path. That worker's email and phone number registration will be reset for all workers, and may be used again.

Note that Checkr Pay allows for the re-use of a Checkr Background Check ID to create multiple workers in the Sandbox environemnt.

Authorizations:
path Parameters
id
required
string

ID of Worker to Reset.

Responses

Request samples

curl -i -X POST \
  https://api.checkrpay.com/customer/v0/sandbox/workers/reset/:id \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE'

Response samples

Content type
text/plain
OK

Reset all Sandbox Account Test Workers

This endpoint is only available in the Checkr Pay Sandbox, and is intended only to facilitate testing.

Checkr Pay requires that each worker associated with your account have a unique phone number and email address.

Calling this endpoint will reset registration data associated with all workers in your sandbox. Worker email and phone number registrations will be reset for all workers, and may be used again.

Note that Checkr Pay allows for the re-use of a Checkr Background Check ID to create multiple workers in the Sandbox environemnt.

Authorizations:

Responses

Request samples

curl -i -X POST \
  https://api.checkrpay.com/customer/v0/sandbox/workers/reset_all \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE'

Payouts

Send payouts to workers.

Create a new Payout

Send a Payout to a worker. To send a payout, call this endpoint with the parameters below.

Checkr Pay returns a newly-created payout in the pending state. The payout is then queued for asynchronous processing by the payouts engine. Payouts are typically processed within 2-3 seconds of creation. If successful, the payout moves to the completed state - indicating that the Payout is settled and the funds have cleared into the worker's account.

Checkr Pay sends your application a webhook for every Payout state change. See the Webhooks page for more information.

Authorizations:
Request Body schema: application/json
workerId
required
string

The ID of the worker to receive this Payout. The worker must be active or pending to receive a payout. If the worker is pending, the payout is queued until the worker activates their account.

metadata
string <= 256 characters

Optional customer-provided Payout metadata. This field is commonly used to label a Checkr Pay worker record with a custom identification value from your database (e.g, a ride ID).

description
string <= 256 characters

A plain language description of the Payout. This will be shown to the worker.

amountCents
required
integer

The Payout amount, in cents.

Responses

Request samples

curl -i -X POST \
  https://api.checkrpay.com/customer/v0/payouts \
  -H 'Content-Type: application/json' \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
    "metadata": "tx_1313101",
    "description": "$100 Payout for a job well done!",
    "amountCents": 10000
  }'

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "metadata": "tx_1313101",
  • "description": "$100 payout for a job well done!",
  • "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
  • "amountCents": 10000,
  • "feeCents": 0,
  • "status": "pending",
  • "createdAt": "2022-09-27T20:41:13.680Z",
  • "completedAt": null,
  • "canceledAt": null,
  • "cancelCode": null
}

Retrieve payouts

Retrieve all Payout objects for a given worker. Filter by created_at date with the created_before and created_after query parameters. This does not include payouts issued via the Create Repayment endpoint.

This is a paginated endpoint. See the Pagination documentation for more information.

Authorizations:
query Parameters
workerId
string

Worker ID to retrieve Payouts for.

Example: workerId=fd09c9d3-067f-488e-937a-313de48da3e0
metadata
string

Search for a Payout with a specific metadata value.

Example: metadata=fd09c9d3-067f-488e-937a-313de48da3e0
created_before
string

Returns payouts created before the input date.

Example: created_before=10-30-2022
created_after
string

Returns payouts created after the input date.

Example: created_after=10-30-2022
queued
string

Returns payouts that are queued

Example: queued=true

Responses

Request samples

curl -i -X GET \
  'https://api.checkrpay.com/customer/v0/payouts?workerId=fd09c9d3-067f-488e-937a-313de48da3e0&metadata=fd09c9d3-067f-488e-937a-313de48da3e0&created_before=10-30-2022&created_after=10-30-2022&queued=true' \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list",
  • "next_href": null,
  • "previous_href": null,
  • "count": 2
}

Retrieve a Payout

Retrieve a single Payout by ID.

Authorizations:
path Parameters
id
required
string

ID of Payout to retrieve.

Responses

Request samples

curl -i -X GET \
  https://api.checkrpay.com/customer/v0/payouts/:id \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "metadata": "payout_12345",
  • "description": "$100 incentive for 09/15/2022 shift at Sacred Heart Hospital Neuro ICU. Thanks for all you do to keep our healthcare system running!",
  • "workerId": "522a2f1b-e0d0-4c72-a37c-5fb6ecf22e9f",
  • "amountCents": 10000,
  • "feeCents": 0,
  • "status": "completed",
  • "createdAt": "2022-09-27T20:41:13.680Z",
  • "completedAt": "2022-09-27T20:42:13.680Z",
  • "canceledAt": null,
  • "cancelCode": null
}

Repay a payout

This feature has special compliance requirements. Contact Checkr Pay Support to enable it.

Send the worker a negative amount payout corresponding to a previous payout. It uses the original payout's amount and description with a Repayment for: prefix.

Authorizations:
path Parameters
id
required
string

ID of payout

Example: 981e4567-f69a-15d3-a156-4126614174839

Responses

Request samples

curl -i -X POST \
  https://api.checkrpay.com/customer/v0/payouts/:id/repay \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "description": "Repayment for: $100 incentive for 09/15/2022 shift at Sacred Heart Hospital Neuro ICU.",
  • "workerId": "522a2f1b-e0d0-4c72-a37c-5fb6ecf22e9f",
  • "amountCents": -10000,
  • "feeCents": 0,
  • "status": "completed",
  • "createdAt": "2022-09-27T20:41:13.680Z",
  • "completedAt": "2022-09-27T20:42:13.680Z",
  • "repaymentFor": "981e4567-f69a-15d3-a156-4126614174839",
  • "canceledAt": null,
  • "cancelCode": null
}

Retrieve repayments

Retrieve all Payout objects created via repayments for a given payout. Filter by created_at date with the created_before and created_after query parameters.

This is a paginated endpoint. See the Pagination documentation for more information.

Authorizations:
path Parameters
id
required
string

ID of payout

Example: 981e4567-f69a-15d3-a156-4126614174839

Responses

Request samples

curl -i -X GET \
  https://api.checkrpay.com/customer/v0/payouts/:id/repayments \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list",
  • "next_href": null,
  • "previous_href": null,
  • "count": 1
}

Tax Records

Manage tax compliance.

Create a new TaxRecord

Call this endpoint to create a new tax form for your worker.

This endpoint returns a newly-created TaxRecord in the pending state. The TaxRecord is then queued for asynchronous processing by the Checkr Pay tax engine, which processes it within 2-3 seconds - and moves it into one of the following states:

  1. waiting_for_approval: this state indicates that the TaxRecord was successfully generated, and is now queued for your approval. To approve the TaxRecord and queue it for filing with the IRS, call the Update a TaxRecord endpoint.

  2. canceled: this state indicates that the TaxRecord failed generation. Contact Checkr Support for more information.

Checkr Pay sends your application a webhook to announce this state change (along with all other state changes to TaxRecords). See the Webhooks page for more information.

Authorizations:
Request Body schema: application/json
workerId
string

The worker this tax record is for. You can only file a tax form for a Worker who has an active account (i.e., status = active), or has previously had an active account that is now closed (i.e., st atus = closed).

taxYear
integer

The year this tax record is for. You can only file tax forms for completed tax years (i.e., wait until January 1, 2023 before filing a tax form for 2022).

taxFormType
string

The type of tax form to generate for the worker.

Values include: "1099-NEC" "1099-MISC"

Responses

Request samples

curl -i -X POST \
  https://api.checkrpay.com/customer/v0/tax_records \
  -H 'Content-Type: application/json' \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
    "taxYear": 2021,
    "taxFormType": "1099-NEC"
  }'

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
  • "taxYear": 2020,
  • "taxFormType": "1099-NEC",
  • "generatedPdf": null,
  • "generatedData": null,
  • "status": "pending",
  • "createdAt": "2022-09-27T20:41:13.680Z",
  • "filedAt": null,
  • "canceledAt": null,
  • "cancelCode": null
}

Retrieve TaxRecords

Retrieve all TaxRecord obejcts satisfying the search criteria. Filter by year range with the first_tax_year and last_tax_year query parameters.

This is a paginated endpoint. See the Pagination documentation for more information.

Authorizations:
query Parameters
workerId
required
string

Worker ID to retrieve tax records for.

Example: workerId=fd09c9d3-067f-488e-937a-313de48da3e0
first_tax_year
integer

First tax year to retrieve tax records for.

Example: first_tax_year=2020
last_tax_year
integer

Last tax year to retrieve tax records for.

Example: last_tax_year=2022

Responses

Request samples

curl -i -X GET \
  'https://api.checkrpay.com/customer/v0/tax_records?workerId=fd09c9d3-067f-488e-937a-313de48da3e0&first_tax_year=2020&last_tax_year=2022' \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "object": "list",
  • "next_href": null,
  • "previous_href": null,
  • "count": 2
}

Retrieve a TaxRecord

Retrieve a single TaxRecord by ID.

Authorizations:
path Parameters
id
required
string

ID of TaxRecord to retrieve or edit.

Responses

Request samples

curl -i -X GET \
  https://api.checkrpay.com/customer/v0/tax_records/:id \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE'

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
  • "taxYear": 2020,
  • "taxFormType": "1099-NEC",
  • "generatedPdf": "VGhpcyBpcyBhIDEwOTkgUERGIGZvcm0u",
  • "generatedData": {
    },
  • "status": "filed",
  • "createdAt": "2022-09-27T20:41:13.680Z",
  • "filedAt": null
}

Update a TaxRecord

Update a single TaxRecord.

Use this endpoint to update the status of a TaxRecord. Valid state changes are as follows:

  • Approve a TaxRecord by changing the status from waiting_for_approval to approved

  • Cancel a TaxRecord by changing the status from pending/waiting_for_approval to canceled.

If you approve a TaxRecord, it is queued for filing with the IRS.
Once filed, it moves into the filed state.

If you cancel a TaxRecord, it is moved into the canceled state and can no longer be edited or filed. If you would like to file the 1099, you will need to create a new TaxRecord.

If properly configured via the admin dashboard, you will receive a webhook for every state change. See the Webhooks page for more information.

Authorizations:
path Parameters
id
required
string

ID of TaxRecord to retrieve or edit.

Request Body schema: application/json
status
string

New status for the TaxRecord.

Values include: "approved" "canceled"

Responses

Request samples

curl -i -X PUT \
  https://api.checkrpay.com/customer/v0/tax_records/:id \
  -H 'Content-Type: application/json' \
  -H 'X-CHECKR-PAY-ACCESS-KEY: YOUR_API_KEY_HERE' \
  -H 'X-CHECKR-PAY-SECRET-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "status": "approved"
  }'

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "workerId": "fd09c9d3-067f-488e-937a-313de48da3e0",
  • "taxYear": 2021,
  • "taxFormType": "1099-MISC",
  • "generatedPdf": null,
  • "generatedData": null,
  • "status": "pending",
  • "createdAt": "2022-09-27T20:41:13.680Z",
  • "filedAt": null
}