KYC Status Handling Guide

This document explains how KYC works for wallets, how to interpret KYC Status and Substatus, and what actions your application must take at each stage.

What Your Application Must Do

Your application must:

Read KYC Status and KYC Substatus from APIs
Drive UI, limits, and feature access based on KYC state
Handle state transitions, including vKYC initiation, Re-do flows, Rejection handling
Support asynchronous updates

How to read status

KYC Status
Represents the high-level verification state of the user.

KYC Substatus
Represents the detailed stage within the KYC process.

⚠️ Always evaluate Status + Substatus together.
Either value alone is insufficient for correct decision-making.

KYC Status, Substatus & Meaning

KYC Status	KYC Substatus	When It Happens	Outcome
`Not Uploaded`	-	Wallet/card is newly created	-
`Min KYC Verified`	`VKYC Pending`	OTP verification completed	-
`Pending`	`Created`	vKYC link generated; call initiated but not completed	-
`Pending`	`Pending`	vKYC completed by user; agent decision pending	-
`Verified`	`Verified`	Agent approved KYC	Accepted
`Failed`	`Rejected`	Agent rejected KYC	Rejected
`Pending`	`Redo`	Agent requested re-do due to mismatch/inconsistency	Redo

End-to-End KYC Flow

Wallet Creation

Call the wallet creation API

API response includes:

Wallet identifier

Initial KYC

KYC Status: Not Uploaded

Meaning

Wallet is allotted

User is not verified

UI Guidance

Show onboarding prompts

Ask user to complete OTP verification

OTP Verification (Minimum KYC)

KYC Status: Min KYC Verified

KYC Substatus: Vkyc Pending

Meaning

Minimum KYC completed

Full KYC is mandatory to unlock full features

Integration Guidance

Allow only min-KYC permitted features

Prompt user to start Video KY

vKYC Link Creation & Initiation

Call the vKYC initiation API

Generate a vKYC link

User opens the link

If the user starts but does not complete the call:

KYC Status: Pending

KYC Substatus: Created

Meaning

KYC is in progress

Video call not completed

UI Guidance

Show “Resume KYC” or “Continue Verification”

Allow regeneration of vKYC link if expired

vKYC Completed – Awaiting Review

Once the user completes the video call:

KYC Status: Pending

KYC Substatus: Pending

Meaning

User action is complete

Agent/auditor review is pending

Integration Guidance

Keep user in restricted/min-KYC state

Do not unlock full features

Poll status or rely on webhooks for updates

Verification Outcomes

After agent review, KYC transitions to one of the following final states

Approved

KYC Status: Verified

KYC Substatus: Verified

Outcome: Accepted

What This Means

User is fully KYC-verified

The load limit assigned is of INR 2 lacs

What You Should Do

Lift KYC-based restrictions

Enable higher limits

Allow all KYC-dependent features

Rejected

KYC Status: FAILED

KYC Substatus: REJECTED

Outcome: Rejected

What This Means

KYC was rejected by the agent

What You Should Do

Block wallet load & Activities

Decide:

Whether retry is allowed

Whether wallet should be closed

Show clear rejection messaging

Provide support or next-step guidance

Re-do Required

KYC Status: Pending

KYC Substatus: Redo

Outcome: Redo

What This Means

Issues found (e.g., unclear video, document mismatch)

User must redo vKYC

What You Should Do

Notify user clearly

Allow re-triggering of vKYC initiation

Keep user in restricted/min-KYC state

Handling Asynchronous Updates

KYC updates are not instantaneous.You should

Poll KYC status APIs at safe intervals

Use webhooks/callbacks where available

Refresh status before rendering:

Wallet details

Limits Assigning

Allow Load

Enable Transaction flows

Error Handling & Edge Cases

User Abandons vKYC

Allow resume

Regenerate link if expired

Multiple Redo Attempts

Consider max retry limits

Escalate to support/compliance if exceeded

What Your Application Must Do#

How to read status#

KYC Status, Substatus & Meaning#

End-to-End KYC Flow#

Wallet Creation#

Initial KYC#

Meaning#

UI Guidance#

OTP Verification (Minimum KYC)#

Meaning#

Integration Guidance#

vKYC Link Creation & Initiation#

Meaning#

UI Guidance#

vKYC Completed – Awaiting Review#

Meaning#

Integration Guidance#

Verification Outcomes#

Approved#

What This Means#

What You Should Do#

Rejected#

What This Means#

What You Should Do#

Re-do Required#

What This Means#

What You Should Do#

Handling Asynchronous Updates#

KYC updates are not instantaneous.You should#

Error Handling & Edge Cases#

User Abandons vKYC#

Multiple Redo Attempts#

What Your Application Must Do

How to read status

KYC Status, Substatus & Meaning

End-to-End KYC Flow

Wallet Creation

Initial KYC

Meaning

UI Guidance

OTP Verification (Minimum KYC)

Meaning

Integration Guidance

vKYC Link Creation & Initiation

Meaning

UI Guidance

vKYC Completed – Awaiting Review

Meaning

Integration Guidance

Verification Outcomes

Approved

What This Means

What You Should Do

Rejected

What This Means

What You Should Do

Re-do Required

What This Means

What You Should Do

Handling Asynchronous Updates

KYC updates are not instantaneous.You should

Error Handling & Edge Cases

User Abandons vKYC

Multiple Redo Attempts