KYC Verification

Know Your Customer (KYC) verification is required before a user can receive payments through Cadana. You submit identity documents and personal information via the API, and Cadana handles automated verification. This page covers the submission requirements, status tracking, and webhook events.

KYC Flow

Status	Meaning	User can transact?
`not started`	KYC has not been submitted	No
`processing`	Documents submitted, verification in progress	No
`approved`	Verification successful	Yes
`rejected`	Verification failed — resubmission needed	No

You may also see pending while verification is underway — treat it like processing and wait for approved or rejected. Most verifications complete automatically within minutes. If automated checks can’t verify the user’s identity, a manual review may take 1-2 business days.

Submit KYC

Submit identity information and documents for a user. Upload document images first using the file upload flow, then pass the returned fileId values. Returns 204 on success. The user’s KYC status moves to processing.

Personal Information

Field	API Field	Required	Rules
First name	`firstName`	Yes	Must match government-issued ID exactly
Last name	`lastName`	Yes	Must match government-issued ID exactly
Date of birth	`dob`	Yes	Format: `YYYY-MM-DD`
Nationality	`nationality`	Yes	2-letter ISO country code (e.g., `US`, `NG`, `KE`)

Identity Document

Field	API Field	Required	Rules
Document type	`idDetails.type`	Yes	See supported types below
Document number	`idDetails.number`	Yes	Unique identifier on the document
Issuing authority	`idDetails.issuedBy`	Yes	Authority that issued the document
Issue date	`idDetails.issuedDate`	Yes	Format: `YYYY-MM-DD`
Expiration date	`idDetails.expirationDate`	Yes	Format: `YYYY-MM-DD`. Must not be expired
Issuing country	`idDetails.issuedCountryCode`	Yes	2-letter ISO country code
Front of ID	`idDetails.frontFileId`	Yes	`fileId` from file upload
Back of ID	`idDetails.backFileId`	No	Required for driver’s licenses and some national IDs
Selfie	`idDetails.selfieFileId`	Yes	Photo of user holding the document

Supported document types:

Document	API Value
Passport	`passport`
Driver’s license	`driver_license`
National ID card	`national_id`
ID card	`id_card`
Voter ID card	`voter_id_card`
PAN card	`pan_card`

Images must be clear and readable with all text visible. Supported formats: JPEG, PNG.

Address (Optional)

If provided, all required address fields must be completed.

Field	API Field	Required
Street address	`address.line1`	Yes
Address line 2	`address.line2`	No
City	`address.city`	Yes
State / Province	`address.state`	Yes
Postal code	`address.postalCode`	Yes
Country	`address.countryCode`	Yes (2-letter ISO code)

An address proof document can be provided via addressProofFileId (utility bill, bank statement, or government document dated within the last 3 months).

Check KYC Status

Retrieve a user’s current KYC status. Response:

{
  "userKyc": {
    "firstName": "John",
    "lastName": "Doe",
    "identity": "approved",
    "address": "not started",
    "idDetails": {
      "country": "US",
      "type": "Drivers license"
    }
  }
}

Identity and address verification are tracked separately. A user needs at minimum identity: "approved" to receive payments. If a verification is rejected, the identityStatusReason or addressStatusReason field explains why.

Resubmit KYC

If a user’s identity or address verification is rejected, use the PATCH endpoint to resubmit corrected information. You can resubmit identity, address, or both in a single request. Resubmission rules:

Section	Can resubmit when
Identity	Status is `rejected`
Address	Status is `not started` or `rejected`

At least one of identity or address must be provided. When a section is included, all of its fields are required.

Resubmit identity only

Resubmit address only

Returns 204 on success. Only the resubmitted section(s) move to processing — approved sections remain unchanged.

Webhook Events

user.kyc.updated

Fired on every KYC status change — processing, approved, or rejected. The type field indicates which verification component changed.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "eventType": "user.kyc.updated",
  "version": "1.0",
  "timestamp": 1765359752,
  "data": {
    "userId": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e",
    "status": "approved",
    "type": "identity",
    "tenantKey": "cad95193904"
  }
}

Field	Description
`userId`	The user whose KYC status changed
`status`	New status: `processing`, `approved`, or `rejected`
`type`	Verification component: `identity` or `address`

For rejected verifications, fetch the user’s KYC details with GET /v1/users/{userId}/kyc to see the failure reason.

user.kyc.expiry

Fired when a user’s identity document is approaching expiry or has expired.

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "eventType": "user.kyc.expiry",
  "version": "1.0",
  "timestamp": 1765359752,
  "data": {
    "userId": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e",
    "stage": "about-to-expire",
    "documentType": "passport",
    "expiryDate": "2026-03-15",
    "tenantKey": "cad95193904"
  }
}

Stage	Meaning
`about-to-expire`	Document expires within 30 days
`in-grace-period`	Expired but within 60-day grace period — existing transactions continue, new ones may be restricted
`expired`	Past grace period — user must re-verify

See Events for all event types and payload details.

Handling Rejections

When KYC is rejected, the user needs to resubmit. Common rejection reasons:

Reason	User action
Document expired	Submit valid, non-expired document
Image unreadable	Retake photo with good lighting
Document damaged	Submit undamaged document
Info mismatch	Verify name and DOB match the document exactly
Unsupported document	Submit an accepted document type

To resubmit, call PATCH /v1/users/{userId}/kyc with corrected information for the rejected section(s). The status resets to processing.

Sandbox Testing

Use sentinel values to simulate KYC approval or rejection in the sandbox environment without waiting for real verification. These sentinels work with both initial submission (POST) and resubmission (PATCH).

In sandbox, always use a sentinel. A submission without one is never resolved, and because resubmission requires a rejected status, the user cannot complete KYC — recover by deleting the sandbox user and re-inviting.

Identity Verification

Set idDetails.number to a sentinel value:

Test Value	Field	Result
`auto-approve`	`idDetails.number`	Identity automatically approved
`auto-reject`	`idDetails.number`	Identity automatically rejected

Address Verification

Set address.line2 to a sentinel value:

Test Value	Field	Result
`auto-approve`	`address.line2`	Address automatically approved
`auto-reject`	`address.line2`	Address automatically rejected

You can combine both sentinels in a single request to auto-resolve identity and address independently. For example, idDetails.number: "auto-approve" with address.line2: "auto-reject" will approve identity and reject address.

When a sentinel is used, the document file IDs (frontFileId, selfieFileId, addressProofFileId) can be omitted — no file upload is needed. If you do pass them, they must reference files you actually uploaded; made-up IDs are rejected with a 404. Without a sentinel, file IDs are required, as in production.

Testing the Resubmission Flow

To test the full rejection-to-resubmission cycle in sandbox:

Submit KYC with idDetails.number: "auto-reject" to get a rejected identity
Resubmit via PATCH with idDetails.number: "auto-approve" to approve it

These test values only work in the sandbox environment and are silently ignored in production. Sentinel values are case-insensitive.

See Sandbox & Testing for all test values.

Next Steps

Working with Files

Upload identity documents before submitting KYC

KYB Requirements

Business verification requirements

Onboard Workers

Create Person and User records

Sandbox & Testing

Test values and simulated scenarios

Get Started

Workforce Management

Payroll & Compliance

White-Label UI

Platform Integration

Payments

Wallets

KYC Flow

Submit KYC

Personal Information

Identity Document

Address (Optional)

Check KYC Status

Resubmit KYC

Resubmit identity only

Resubmit address only

Webhook Events

user.kyc.updated

user.kyc.expiry

Handling Rejections

Sandbox Testing

Identity Verification

Address Verification

Testing the Resubmission Flow

Next Steps

Working with Files

KYB Requirements

Onboard Workers

Sandbox & Testing

​KYC Flow

​Submit KYC

​Personal Information

​Identity Document

​Address (Optional)

​Check KYC Status

​Resubmit KYC

​Resubmit identity only

​Resubmit address only

​Webhook Events

​user.kyc.updated

​user.kyc.expiry

​Handling Rejections

​Sandbox Testing

​Identity Verification

​Address Verification

​Testing the Resubmission Flow

​Next Steps

Working with Files

KYB Requirements

Onboard Workers

Sandbox & Testing

KYC Flow

Submit KYC

Personal Information

Identity Document

Address (Optional)

Check KYC Status

Resubmit KYC

Resubmit identity only

Resubmit address only

Webhook Events

user.kyc.updated

user.kyc.expiry

Handling Rejections

Sandbox Testing

Identity Verification

Address Verification

Testing the Resubmission Flow

Next Steps