Employee Onboarding

This guide explains the requirements that must be satisfied before an employee can complete onboarding and begin using Paytient services.

Overview

The Get Employee Onboarding Requirements Status endpoint returns the current status of all onboarding requirements for a given employee. Each requirement must be fulfilled before the employee can complete onboarding.

See the API Reference for full endpoint details and request/response schemas.

API Version

The Get Employee Onboarding Requirements Status endpoint is only available in API version 2027-01-01 (the latest version).

Checking Requirement Status

Use the Get Employee Onboarding Requirements Status endpoint to see which requirements are fulfilled and which are missing.

See the API Reference for the complete endpoint documentation and full response schema.

The Onboarding Requirements

Table of Contents:

Employment Status
Eligibility Status
Birthday
Over 18
Valid Address
Payroll Schedule
SSN (Social Security Number)
Repayment Process
Agreements
Enrolled in Onboarding
ATR (Ability to Repay)
Identity Verification

1. Employment Status

What it is: Employee must have an active employment status with the employer.

Requirement: isEmployed must be set to true

How to fulfill:

Set during employee creation using POST /api/employers/{employerId}/employees (see API Reference)
Update using PATCH /api/employers/{employerId}/employees/{employeeId} (see API Reference)

Example PATCH operation:

{
  "op": "replace",
  "path": "/isEmployed",
  "value": true
}

Common issues:

isEmployed set to false
Field not set during employee creation

2. Eligibility Status

What it is: Employee must be eligible to participate in the employer's benefit program.

Requirement: isEligible must be set to true

How to fulfill:

Set during employee creation using POST /api/employers/{employerId}/employees (see API Reference)
Update using PATCH /api/employers/{employerId}/employees/{employeeId} (see API Reference)

Example PATCH operation:

{
  "op": "replace",
  "path": "/isEligible",
  "value": true
}

Common issues:

isEligible set to false
Field not set during employee creation

3. Birthday

What it is: Employee's date of birth must be provided.

Requirement: birthDate field must be populated

How to fulfill:

Set during employee creation using POST /api/employers/{employerId}/employees (see API Reference)
Set during eligibility file SFTP upload via Birth Date field (see Eligibility File Spec)
Update using PATCH /api/employers/{employerId}/employees/{employeeId} (see API Reference)

Example PATCH operation:

{
  "op": "replace",
  "path": "/birthDate",
  "value": "1990-05-15"
}

Common issues:

birthDate is null or missing
Date format is incorrect (must be ISO 8601: YYYY-MM-DD)

4. Over 18

What it is: Employee must be at least 18 years old.

Requirement: birthDate must indicate the employee is 18 years or older

How to fulfill:

Automatically calculated from birthDate field
Ensure the provided birth date makes the employee at least 18 years old

Common issues:

Employee is under 18 years old
Birth date is incorrectly entered

5. Valid Address

What it is: Employee must have a complete residential address.

Requirement: All address fields must be populated:

address.line1
address.city
address.state
address.postalCode

How to fulfill:

Set during employee creation using POST /api/employers/{employerId}/employees (see API Reference)
Set during eligibility file SFTP upload via Address 1, Address 2, City, State, and ZIP Code fields (see Eligibility File Spec)
Update using PATCH /api/employers/{employerId}/employees/{employeeId} (see API Reference)

Example PATCH operation:

{
  "op": "replace",
  "path": "/address",
  "value": {
    "line1": "123 Main Street",
    "line2": "Apt 4B",
    "city": "Chicago",
    "state": "IL",
    "postalCode": "60601"
  }
}

Common issues:

Missing required address fields
Invalid state code (must be valid 2-letter US state code)
Invalid postal code format
P.O. boxes are not accepted - must be a physical residential address

6. Payroll Schedule

What it is: Employee must be assigned to a payroll schedule for repayment processing.

Requirement: payrollScheduleId must be set to a valid payroll schedule

How to fulfill:

Payroll schedules cannot be created or modified via the Partner API
Contact your Paytient account manager to set up payroll schedules
Once a payroll schedule exists, assign the employee to it using PATCH /api/employers/{employerId}/employees/{employeeId} (see API Reference)

Example PATCH operation:

{
  "op": "replace",
  "path": "/payrollScheduleId",
  "value": 12345
}

Common issues:

No payroll schedule created for employer
Employee not assigned to any payroll schedule
Assigned to an inactive payroll schedule

What it is: Employee's Social Security Number must be provided for identity verification.

Requirement: ssn field must be populated

How to fulfill:

Set during employee creation using POST /api/employers/{employerId}/employees (see API Reference)
Set during eligibility file SFTP upload via SSN field (see Eligibility File Spec)
Update using PATCH /api/employers/{employerId}/employees/{employeeId} (see API Reference)

Example PATCH operation:

{
  "op": "replace",
  "path": "/ssn",
  "value": "123-45-6789"
}

Common issues:

SSN not provided during employee creation
Invalid SSN format
SSN cannot start with the number 9

8. Repayment Process

What it is: The employer's repayment process must be configured and the employee must have a valid repayment method.

Requirement: For this requirement to be fulfilled, one of the following must be true:

Employer has payroll deduction repayment enabled
Employer has payment method repayment enabled AND the employee has added a payment method (credit card or bank account)

How to fulfill:

Repayment options are configured by Paytient
Cannot be changed via Partner API
Contact your Paytient account manager to enable the appropriate repayment option(s) for the employer
If the employer uses payment method repayment (instead of payroll deduction), you must implement a flow for employees to add a payment method using the Payment Methods API endpoints

Common issues:

Employer repayment process not configured
Employer account not fully set up
Payment method repayment is enabled but employee has not added a payment method

9. Agreements

What it is: Employee must accept all required legal agreements.

Requirement: Employee must accept all required agreements

How to check agreement status:

Use GET /api/employers/{employerId}/employees/{employeeId}/agreements (see API Reference) to retrieve all agreements for an employee. The response includes an acceptedOn field for each agreement:

If acceptedOn is null, the agreement has not been accepted yet
All required agreements must have a non-null acceptedOn timestamp
The tag field indicates the agreement version

How to record acceptance:

Once you get the list of agreements from the endpoint above, you must have the user accept each one using POST /api/employers/{employerId}/employees/{employeeId}/agreements/{agreementId} (see API Reference)

Example request body:

{
  "agreementTag": "PrivacyPolicy_V4",
  "acceptedAt": "2024-03-19T10:30:00Z"
}

See the API Reference for complete request/response details.

Common issues:

Agreements not accepted (acceptedOn is null)
Old agreement versions accepted (need latest versions - check the tag version)
Wrong language parameter used

10. Enrolled in Onboarding

What it is: Onboarding process must be formally initiated for the employee.

Requirement: Employee must be enrolled in onboarding when they are created

How to fulfill:

When creating a new employee using POST /api/employers/{employerId}/employees (see API Reference), set enrollInNewOnboarding to true in the request body.

Example field in create employee request:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "enrollInNewOnboarding": true
}

This automatically enrolls the employee in the onboarding process upon creation. See the API Reference for complete schema details.

Common issues:

enrollInNewOnboarding set to false or omitted when creating employee
Employee created without onboarding enrollment
Attempting to use deprecated /onboarding/initiate endpoint

11. ATR (Ability to Repay)

What it is: Employee must demonstrate ability to repay their balance through financial assessment.

Requirement: Employee must submit and pass the Ability to Repay check:

Annual income must be provided (required)
Monthly financial obligations must be provided
Assessment must result in "Passed ATR" status

Note: This requirement will only work if enrollInNewOnboarding was set to true in step 10 (Enrolled in Onboarding).

What counts as income:

Income can include current or expected salary, Social Security, retirement benefits, welfare, alimony, child support, savings accounts, investments, and separate maintenance payments. You do not need to report alimony, child support, or separate maintenance if you do not want it considered as a basis for repayment.

What counts as monthly obligations (expenses):

Expenses include any recurring payments you make to a creditor or lender for the money borrowed, such as student loans or a mortgage, and fixed costs, such as rent or electric bills.

How to fulfill:

Use POST /api/employers/{employerId}/employees/{employeeId}/atr (see API Reference) to submit the employee's financial information.

Example request body:

{
  "annualIncome": 65000,
  "monthlyObligations": 1500
}

See the API Reference for complete request/response details.

How it's calculated:

System evaluates income vs. obligations
Determines maximum allowable balance and repayment terms
Returns pass/fail status

Common issues:

ATR not submitted
Annual income not provided (required)
Failed ATR due to insufficient income vs. obligations
Can reapply after 30 days if initially failed
Employee was not enrolled in onboarding (enrollInNewOnboarding not set to true)

12. Identity Verification

What it is: Employee identity must be verified through CIP (Customer Identification Program) compliance process.

Requirement: Identity verification must be completed successfully

How to fulfill:

Identity verification is a multi-step process that involves initiating verification, handling webhook responses, and potentially uploading documentary evidence. This requirement depends on having valid employee data (SSN, birth date, and address) already in place.

High-level flow:

Initiate identity verification
Receive webhook indicating success, failure, or need for documentary evidence
If documentary evidence is needed, upload documents and wait for final webhook

Common issues:

Missing required employee data (SSN, DOB, address) - ensure requirements #3, #5, and #7 are met first
Identity verification failed
Documentary evidence required but not provided
Verification pending for extended period

tip

See the Identity Verification Flow guide for complete step-by-step instructions, webhook details, and error handling.

Onboarding Completion

Once all requirements are fulfilled, the Get Employee Onboarding Requirements Status endpoint will return a response with a complete field set to true at the root of the response, indicating that the employee has successfully completed onboarding and can begin using Paytient services.

Common Onboarding Issues

Issue	Cause	Solution
Requirements not updating	Data updated but validation not triggered	Wait a few seconds and check again; system validates asynchronously
ATR keeps failing	Income too low vs. obligations	Review employee financial information; they can reapply after 30 days
Identity verification stuck	Missing required data or pending review	Check for missing SSN, DOB, or address; may need documentary evidence
Agreements not showing as fulfilled	Old agreement versions	Employee must accept latest versions of all agreements
Payroll schedule missing	Not created for employer	Create payroll schedule first, then assign to employee

Getting Help

If you encounter issues with employee onboarding:

Check requirement status: Use the Get Employee Onboarding Requirements Status endpoint to see exactly what's missing
Review error messages: API responses include specific details about validation failures
Verify data completeness: Ensure all required fields are populated correctly
Check employer setup: Confirm repayment process and other employer-level settings are configured
Contact support: Reach out to your Paytient implementation contact with:
- Employee ID
- Current requirement status response
- Steps already attempted
- Any relevant error messages

Related Resources:

Overview​

Checking Requirement Status​

The Onboarding Requirements​

1. Employment Status​

2. Eligibility Status​

3. Birthday​

4. Over 18​

5. Valid Address​

6. Payroll Schedule​

7. SSN (Social Security Number)​

8. Repayment Process​

9. Agreements​

10. Enrolled in Onboarding​

11. ATR (Ability to Repay)​

12. Identity Verification​

Onboarding Completion​

Common Onboarding Issues​

Getting Help​

Overview

Checking Requirement Status

The Onboarding Requirements

1. Employment Status

2. Eligibility Status

3. Birthday

4. Over 18

5. Valid Address

6. Payroll Schedule

7. SSN (Social Security Number)

8. Repayment Process

9. Agreements

10. Enrolled in Onboarding

11. ATR (Ability to Repay)

12. Identity Verification

Onboarding Completion

Common Onboarding Issues

Getting Help