Identity Verification Flow

This guide describes the complete identity verification (IDV) flow for employees, including how to handle missing data, verification responses, and documentary evidence requirements.

Overview

The identity verification process validates employee identity information before they can use certain Paytient services. This process involves initiating verification, handling potential missing data, and responding to verification outcomes from webhooks. See the API Reference for full endpoint details.

API Version Requirement

Identity verification endpoints are only available in API version 2027-01-01 or later. Ensure you set the api-version header appropriately.

Flow Diagram

The identity verification flow follows these steps:

1. POST to Initiate IDV
   ├─ 202 Success → Wait for Webhook
   └─ 422 Error → Add Missing Data → Retry Step 1
   ↓
2. Webhook Received
   ├─ identity-verification.success → Complete
   ├─ identity-verification.failed → Handle Failure
   └─ identity-verification.needs-documentary-evidence → Upload Evidence → Return to Step 2

Step-by-Step Process

Step 1: Initiate Identity Verification

Use the identity verification initiate endpoint (see API Reference) to start the verification process.

Successful Response (202 Accepted):

This indicates that the employee data has been validated and sent to the verification provider. Proceed to Step 2 to listen for webhook responses.

Failure Response (422 Unprocessable Entity):

If the initiation request fails with a 422 Unprocessable Entity error, the response will specify which required fields are missing from the employee record.

Update Missing Employee Data

Use the PATCH Employee endpoint to add the missing field(s).

After successfully updating the employee data, retry Step 1 to initiate identity verification again.

Step 2: Listen for Webhook Responses

Once identity verification is successfully initiated, the verification provider will process the request. You'll receive one of three possible webhook events:

Webhook 1: Success

Event: identity-verification.success

Description: The employee has passed identity verification. No further action needed.

Webhook 2: Failed

Event: identity-verification.failed

Description: The employee has failed identity verification and cannot proceed with identity verification at this time. Handle the failure according to your business requirements.

Webhook 3: Needs Documentary Evidence

Event: identity-verification.needs-documentary-evidence

Description: The employee needs to provide additional documentary evidence to complete their identity verification.

Action Required: Upload the required documentary evidence.

Upload Documentary Evidence (if applicable)

When documentary evidence is required, use the Upload Evidence endpoint to submit the necessary documents.

After successfully uploading the required evidence, return to Step 2 and listen for another webhook response.

Error Handling

Common Error Scenarios

Error Code	Description	Solution
401 Unauthorized	Invalid or expired access token	Refresh your access token
404 Not Found	Employee or employer not found	Verify the employerId and employeeId are correct
422 Unprocessable Entity	Missing required employee data	Use PATCH Employee endpoint to add missing fields, then retry
429 Too Many Requests	Rate limit exceeded	Implement exponential backoff and retry

Best Practices

• check_circle Validate data before initiating: Ensure all required fields are present before calling the initiate endpoint to avoid unnecessary API calls
• check_circle Set up webhooks first: Configure webhook endpoints before initiating identity verification to avoid missing events
• check_circle Verify webhook signatures: Always validate the api-version header to ensure webhook authenticity
• check_circle Store verification status: Track the identity verification status in your system for each employee
• check_circle Provide user feedback: Keep employees informed about their verification status and next steps

Getting Help

If you encounter issues with identity verification:

1. Check error messages: Review the specific error details returned in the API response
2. Verify API version: Ensure you're using API version 2027-01-01 or later
3. Review webhook logs: Check that webhook events are being received and processed correctly
4. Contact support: Reach out to your Paytient implementation contact with:
   • Employee ID
   • Timestamp of the issue
   • Full error messages or webhook payloads
   • Steps you've already tried

Testing Identity Verification

Use the sandbox environment to test the complete identity verification flow, including success, failure, and documentary evidence scenarios, before deploying to production.

In order to simulate different verification outcomes, you can use the simulateResult field when initiating identity verification. Without this field or by setting it to passed, identity verification will always return a successful result in the sandbox environment. By setting the simulateResult to failed or documents_needed, you can test the corresponding webhook responses and ensure your system handles them correctly.