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

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.

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.

(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.

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

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

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

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.

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

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.

At the end of the tax year, file a 1099 for the worker as follows. --- >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

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

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

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

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.

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.

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.

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.

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)

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.

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-Checkrpay-Signature. The hash signature is generated with the HMAC algorithm, using a pre-shared 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.

When requesting that Checkr Pay activate a webhook endpoint for you, we will point the webhooks for your environment at your defined endpoint. We will generate a separate secret key that we will share with you.

Example hash signature computation:

Sample calculated HMAC Value: e08cb839c1ca79d32683ffb95de0519cf6c4d23d22785696289e69695941f9f5

Generated from the following: Sample secret key: JSdaWqpxuQsT0J9qMped8PLTjMvsMnsg Sample object

  {
    "createdAt": "2024-11-04T19:30:35.476Z",
    "data": {
      "object": {
          "amountCents": -20000,
          "createdAt": "2024-11-04T19:30:35.284Z",
          "description": "Repayment for: PayoutTest",
          "feeCents": 0,
          "id": "ed87cb1e-eb78-41c2-b978-40c4da93794f",
          "issuanceStrategy": {
              "name": "instant"
          },
          "object": "payout",
          "repaymentFor": "f15f64e7-a333-4adc-bb1d-d5c63123c016",
          "status": "pending",
          "workerId": "851cc9cf-a7d7-45c5-9f7d-09e1baf6f0ea"
      }
  },
  "id": "672920dbcd9b36bf966fbc49",
  "object": "event",
  "type": "payout.repayment_created"
}

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.

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 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:

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. Additionally, if you have chosen to issue payouts using an issuanceStrategy such as manual, you will get webhooks sent to you after taking action such as releasing or canceling a queued payout for a worker.

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

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:

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.

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).

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.

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

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

   • Height > 460px

   • Width > 350px

4. 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.

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.

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

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.

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 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.

Paginated responses include the following attributes:

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:

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.

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

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:

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.

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:

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.

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.

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.

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.

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.

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.

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.

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.

Onboard and manage workers.

Send payouts to workers.

Manage tax compliance.