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

### <span style="color:#7b2cbf">What Your Application Must Do</span>

Your application **must**:

<Icon icon="material-outline-numbers"color="#7b2cbf"/> Read KYC Status and KYC Substatus from APIs
<Icon icon="material-outline-numbers"color="#7b2cbf"/> Drive UI, limits, and feature access based on KYC state
<Icon icon="material-outline-numbers"color="#7b2cbf"/> Handle state transitions, including vKYC initiation, Re-do flows, Rejection handling
<Icon icon="material-outline-numbers"color="#7b2cbf"/> Support asynchronous updates

### <span style="color:#7b2cbf">How to read status</span>

1.  **KYC Status** 
 Represents the **high-level verification state** of the user.
2.  **KYC Substatus** 
Represents the **detailed stage** within the KYC process.

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

### <span style="color:#7b2cbf">KYC Status, Substatus & Meaning</span>

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

### <span style="color:#7b2cbf">End-to-End KYC Flow</span>

#### **<Icon icon="ph-bold-number-circle-one"color="#7b2cbf"/>** <span style="color:#7b2cbf">Wallet Creation</span>

        - Call the **wallet creation API**
        - API response includes:
         - Wallet identifier
     
#### **<Icon icon="material-outline-numbers"color="#000000"/>** Initial KYC
    - KYC Status: `Not Uploaded`
    
#### **<Icon icon="material-outline-numbers"color="#000000"/>** Meaning
  - Wallet is allotted
  - User is **not verified**
      
#### **<Icon icon="material-outline-numbers"color="#000000"/>** UI Guidance
    - Show onboarding prompts
    - Ask user to complete OTP verification
    
#### **<Icon icon="ph-bold-number-circle-two"color="#7b2cbf"/>** <span style="color:#7b2cbf">OTP Verification (Minimum KYC)</span>
    
    - KYC Status: `Min KYC Verified`
    - KYC Substatus: `Vkyc Pending`
      
#### **<Icon icon="material-outline-numbers"color="#000000"/>** Meaning
    - Minimum KYC completed
    - Full KYC is mandatory to unlock full features

#### **<Icon icon="material-outline-numbers"color="#000000"/>** Integration Guidance
    - Allow only min-KYC permitted features
    - Prompt user to start Video KY 
    
#### **<Icon icon="ph-bold-number-circle-three"color="#7b2cbf"color="#7b2cbf"/>** <span style="color:#7b2cbf">vKYC Link Creation & Initiation</span>
    - 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`
#### **<Icon icon="material-outline-numbers"color="#000000"/>** Meaning
    - KYC is in progress
    - Video call not completed

#### **<Icon icon="material-outline-numbers"color="#000000"/>** UI Guidance
    - Show “Resume KYC” or “Continue Verification”
    - Allow regeneration of vKYC link if expired

#### **<Icon icon="ph-bold-number-circle-four"color="#7b2cbf"color="#7b2cbf"/>** <span style="color:#7b2cbf">vKYC Completed – Awaiting Review</span>
 
    - Once the user completes the video call:
        - KYC Status: `Pending`
        - KYC Substatus: `Pending`

#### **<Icon icon="material-outline-numbers"color="#000000"/>** Meaning
    - User action is complete
    - Agent/auditor review is pending

#### **<Icon icon="material-outline-numbers"color="#000000f"/>** Integration Guidance
    - Keep user in restricted/min-KYC state
    - Do **not** unlock full features
    - Poll status or rely on webhooks for updates

### <span style="color:#7b2cbf">Verification Outcomes</span> 

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


<Container>
### <span style="color:#7b2cbf">Approved</span>

- KYC Status: `Verified`
- KYC Substatus: `Verified`
- Outcome: **Accepted**

#### <Icon icon="material-outline-numbers"color="#000000"/> What This Means
- User is fully KYC-verified
- The load limit assigned is of INR 2 lacs

#### <Icon icon="material-outline-numbers"color="#000000"/> What You Should Do
- Lift KYC-based restrictions
- Enable higher limits
- Allow all KYC-dependent features

</Container>


<Container>
### <span style="color:#7b2cbf">Rejected</span>

- KYC Status: `FAILED`
- KYC Substatus: `REJECTED`
- Outcome: **Rejected**

#### <Icon icon="material-outline-numbers"color="#000000"/> What This Means
- KYC was rejected by the agent

#### <Icon icon="material-outline-numbers"color="#000000"/> 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

</Container>


<Container>
### <span style="color:#7b2cbf">Re-do Required</span>
- KYC Status: `Pending`
- KYC Substatus: `Redo`
- Outcome: **Redo**

#### <Icon icon="material-outline-numbers"color="#000000"/> What This Means
- Issues found (e.g., unclear video, document mismatch)
- User must redo vKYC

#### <Icon icon="material-outline-numbers"color="#000000"/> What You Should Do
- Notify user clearly
- Allow re-triggering of vKYC initiation
- Keep user in restricted/min-KYC state
</Container>


### <span style="color:#7b2cbf">Handling Asynchronous Updates</span> 

#### <Icon icon="material-outline-numbers"color="#7b2cbf"/> 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

### <span style="color:#7b2cbf">Error Handling & Edge Cases</span> 

#### <Icon icon="material-outline-numbers"color="#7b2cbf"/> **User Abandons vKYC**
- Allow resume
- Regenerate link if expired

#### <Icon icon="material-outline-numbers"color="#7b2cbf"/> **Multiple Redo Attempts**
- Consider max retry limits
- Escalate to support/compliance if exceeded