1. Stage 7 Objective
Live selfie is captured, liveness detection confirms a real person, and the face is matched against the Aadhaar photo obtained in Stage 5. The stp_face_flag feeds the STP decision engine. Location is confirmed to be within India.
Key Outcome
This stage produces three critical signals: liveness_passed (real person confirmed), face_match_score (selfie vs Aadhaar photo similarity), and stp_face_flag (STP or NON_STP based on score). The Aadhaar photo is deleted after face match per UIDAI compliance.
2. Preconditions
| Condition | Required Value | Notes |
|---|
lead.state |
BANK_VERIFIED |
Customer must have completed Stage 6 (bank verification) before entering Stage 7 |
aadhaar_photo_path |
Must be set from Stage 5 |
If absent, face match automatically results in NON_STP. Liveness still proceeds. |
| Location permission |
Must be granted |
Required for geolocation verification. If denied, follow location scenario logic. |
Missing Aadhaar Photo
If aadhaar_photo_path is not available from Stage 5, the face match step is skipped and stp_face_flag is automatically set to NON_STP. The liveness check still proceeds normally.
3. Assisted Journey Handoff Link
For FRANCHISE / BRANCH channels, the RM can share a handoff link via WhatsApp or Copy. The customer opens the link and lands directly on the selfie screen. No OTP or login is required for this handoff.
Handoff Scope
The handoff link is channel-specific (FRANCHISE/BRANCH only). The link targets the selfie capture screen directly, bypassing authentication since the session context is embedded in the link token.
4. Backend Flow
1
Check location permission (reuse from Stage 0 if same session)
2
If location is outside India: DROP_LOCATION_OUTSIDE_INDIA (permanent drop — journey terminated)
3
Liveness SDK launched — Hyperverge (primary), AiNXT (fallback)
4
Liveness check executed: live movement detection, lighting validation, anti-spoofing checks
5
Liveness passed → proceed to face match
6
Liveness failed (attempt 1 or 2) → retry with guidance to customer
7
Liveness failed (attempt 3) → CS Journey CS_LIVENESS_DOWN
8
Face match: selfie compared against Aadhaar photo from Stage 5
9
Face match score 70–100 = STP, score 1–69 = NON_STP
10
Face match score 0 (attempt 1) → retry (full liveness + face match flow repeats)
11
Face match score 0 (attempt 2) → DROP_FACE_MATCH_FAIL (permanent drop)
12
Aadhaar photo deleted after face match (UIDAI compliance). Selfie stored for AOF generation.
UIDAI Compliance
The Aadhaar photo must be deleted immediately after the face match comparison is complete. This is a regulatory requirement. The aadhaar_photo_deleted_at timestamp must be recorded.
5. Liveness Attempt Table
| Attempt | Result | Action |
|---|
| Attempt 1 |
Pass |
Proceed to face match |
| Attempt 1 |
Fail — SDK error |
Retry liveness. Switch to fallback vendor (AiNXT) if primary (Hyperverge) failed. |
| Attempt 1 |
Fail — customer unable |
Retry with guidance (lighting, positioning instructions shown to customer) |
| Attempt 2 |
Pass |
Proceed to face match |
| Attempt 2 |
Fail |
Retry with guidance. Final attempt remaining. |
| Attempt 3 |
Pass |
Proceed to face match |
| Attempt 3 |
Fail |
CS Journey CS_LIVENESS_DOWN. Lead placed on hold for customer support resolution. |
Vendor Fallback
If Hyperverge SDK fails on attempt 1, the system should switch to AiNXT for subsequent attempts. Both vendor results are logged in liveness_verifications.
6. Face Match Scoring
| Score Range | Result | Action |
|---|
70 – 100 |
STP |
stp_face_flag = STP. Face match passed. Proceed to exit state. |
1 – 69 |
NON_STP |
stp_face_flag = NON_STP. Face match below threshold. Journey continues but flagged for manual review. |
0 (attempt 1) |
Retry |
Prompt customer: “Try again with better lighting.” One retry allowed. Full liveness + face match flow repeats. |
0 (attempt 2) |
DROP_FACE_MATCH_FAIL |
Permanent drop. lead.state = DROPPED. Journey terminated. |
Face Match Retry = Full Flow Repeat
When face match returns a score of 0 and a retry is triggered, the entire liveness + face match flow repeats from step 3 onward. The customer must redo the live selfie capture before the face match runs again.
7. Location Scenarios
| Scenario | Behavior | Outcome |
|---|
| Location granted at Stage 0, same session |
Reuse existing geolocation data |
No re-prompt. Proceed with cached location. |
| Resumed session (different session from Stage 0) |
Re-request location permission |
Fresh geolocation capture required. |
| Location denied once |
Re-prompt user for location access |
Show explanation of why location is needed. Allow retry. |
| Location denied twice |
Block journey progress |
Customer cannot proceed until location permission is granted. |
| OS-level location block |
Show device settings instructions |
Guide customer to enable location in device settings. |
| Location is outside India |
DROP_LOCATION_OUTSIDE_INDIA |
Permanent drop. Journey terminated immediately. |
| Geocoding fails (API error) |
Retry geocoding once |
If retry fails, route to CS Journey for manual resolution. |
8. Backend Validations
| Validation | Condition | Result | Type | Severity |
|---|
| Location outside India |
Geolocation country != India |
DROP_LOCATION_OUTSIDE_INDIA |
Permanent Drop |
P1 |
| Liveness 3 consecutive failures |
All 3 liveness attempts failed |
CS_LIVENESS_DOWN — CS Journey hold |
CS Journey |
P1 |
| Face match score 0, attempt 2 |
Face match returns 0 on second attempt |
DROP_FACE_MATCH_FAIL |
Permanent Drop |
P1 |
| Aadhaar photo absent |
aadhaar_photo_path not set from Stage 5 |
stp_face_flag = NON_STP automatically |
Auto NON_STP |
P2 |
| File storage failure |
Selfie cannot be saved to configured drive |
P1 alert raised. Retry storage. If persistent, route to CS Journey. |
System Alert |
P1 |
9. Existing SP Mapping
9.1 Stored Procedures (Old System)
These stored procedures from the legacy system map to Stage 7 functionality. They serve as reference for what the new backend must replicate:
| Stored Procedure | Purpose | New Backend Equivalent |
|---|
USP_EKYC_HV_LIVEPHOTO_LOG_SJET |
Log Hyperverge live photo request/response |
liveness_verifications table insert (vendor = hyperverge) |
USP_SAVE_LIVEPHOTO_RESPONSE_SJET |
Save live photo capture response details |
liveness_verifications table insert + document_path_info for selfie storage |
USP_AINXT_LIVEPHOTO_RESPONSE_DETAILS_SJET |
Save AiNXT liveness response details |
liveness_verifications table insert (vendor = ainxt) |
USP_UPDATE_FACE_PROOF_SJET |
Update face proof upload status |
document_path_info update for selfie path + leads.selfie_path |
USP_GET_FACE_MATCH_SERVICE_SJET |
Retrieve face match service configuration |
Provider configuration lookup for face match vendor selection |
USP_INSERT_AINXT_FACEAPI_REQUEST_SJET |
Log AiNXT face match API request |
liveness_verifications table insert (type = face_match, vendor = ainxt) |
USP_INSERT_AINXT_FACEAPI_RESPONSE_SJET |
Log AiNXT face match API response |
liveness_verifications response payload update |
USP_INSERT_LIVEPHOTO_LOCATION_DETAILS_LOG_SJET |
Log geolocation details captured during live photo |
leads geolocation fields + journey_stage_events metadata |
USP_INSERT_UPDATE_STP_FLAG_SJET |
Insert or update STP flag based on face match result |
leads.stp_face_flag update |
9.2 Old External API Calls
Legacy API methods that the new backend must integrate with (or replace):
| Old API Method | Vendor | Purpose |
|---|
LivePhotoAPI.AINXTRequestAPI() |
AiNXT |
AiNXT liveness detection request |
LivePhotoAPI.HypervergeRequestAPI() |
Hyperverge |
Hyperverge liveness SDK integration |
LivePhotoAPI.AINXTRequestGetImageAPI() |
AiNXT |
Retrieve image from AiNXT for face match comparison |
9.3 Old Database Tables
Legacy tables that map to Stage 7 data storage:
| Old Table | Purpose | New Backend Equivalent |
|---|
TBL_CLIENT_LIVEPHOTO_RESPONSE_DETAILS |
Hyperverge live photo response storage |
liveness_verifications |
TBL_CLIENT_AINXT_LIVEPHOTO_RESPONSE_DETAILS |
AiNXT live photo response storage |
liveness_verifications |
TBL_LIVEPHOTO_LOCATION_DETAILS_LOG |
Geolocation details during live photo |
leads geolocation fields + journey_stage_events |
TBL_CLIENT_PROOFUPLOAD |
Proof document upload tracking |
document_path_info |
TBL_IPV_DETAILS |
In-Person Verification details |
liveness_verifications |
TBL_LIVE_PHOTO_LOCATION_EXCEPTION |
Location exception logging |
journey_stage_events (event = LOCATION_EXCEPTION) |
TBL_PINCODE_MASTER |
Pincode-to-city/state reference |
Geocoding API replaces pincode lookup (AiNXT Geolocation fallback) |
10. Error / Drop Codes
| Code | Type | Trigger | User Impact |
|---|
DROP_LOCATION_OUTSIDE_INDIA |
Permanent Drop |
Geolocation confirms customer is outside India |
lead.state = DROPPED. Journey terminated permanently. Customer cannot proceed. |
CS_LIVENESS_DOWN |
CS Journey |
Liveness check failed on all 3 attempts |
Lead placed on hold. Routed to customer support for manual resolution. |
DROP_FACE_MATCH_FAIL |
Permanent Drop |
Face match score = 0 on second attempt |
lead.state = DROPPED. Journey terminated permanently. |
BE_LOC_001 |
Backend Error |
Geolocation API failed / timed out |
Retry geolocation. If persistent, route to CS Journey. |
BE_LOC_002 |
Backend Error |
Geocoding reverse lookup failed (coordinates to address) |
Retry once. If second attempt fails, route to CS Journey. |
11. Exit State
After Stage 7 completes successfully, the following fields are populated:
| Field | Value / Source | Notes |
|---|
lead.state |
LIVENESS_DONE |
Set upon successful liveness + face match completion |
liveness_passed |
true |
Confirms real person detected by liveness SDK |
liveness_vendor |
hyperverge | ainxt |
Which vendor successfully completed the liveness check |
face_match_score |
0 – 100 |
Similarity score between selfie and Aadhaar photo |
stp_face_flag |
STP | NON_STP |
STP if score 70–100; NON_STP if score 1–69 or Aadhaar photo absent |
selfie_path |
File path on configured drive |
Stored for AOF (Account Opening Form) generation. Not S3. |
geolocation_city |
City name from geocoding |
Derived from device geolocation coordinates |
geolocation_country |
Country name from geocoding |
Must be “India” for journey to proceed |
aadhaar_photo_deleted_at |
Timestamp (UTC) |
Recorded when Aadhaar photo is deleted post face match (UIDAI compliance) |
STP Decision Feed
The stp_face_flag is consumed by the downstream STP decision engine. A value of STP contributes positively to the overall STP eligibility. NON_STP flags the lead for manual review at the face match level.
12. Vendor Calls
| Vendor / System | Purpose | When Called | Primary / Fallback |
|---|
| Device Geolocation API |
Capture customer device GPS coordinates |
Stage entry (or reuse from Stage 0 if same session) |
Primary |
| AiNXT Geolocation |
Reverse geocoding (coordinates to city/country) |
After GPS coordinates captured |
Fallback (if device geocoding insufficient) |
| Hyperverge SDK |
Liveness detection (movement, lighting, anti-spoofing) |
Selfie capture screen |
Primary |
| AiNXT Liveness |
Liveness detection (fallback) |
If Hyperverge SDK fails |
Fallback |
| AiNXT CV Model |
Face match — selfie vs Aadhaar photo comparison |
After liveness passed |
Primary |
| Hyperverge Face Match |
Face match (fallback) |
If AiNXT CV Model fails |
Fallback |
| File Storage |
Selfie image persistence on configured drive |
After liveness passed, before face match |
Configured drive (not S3) |
| CleverTap |
Event tracking (liveness result, face match result) |
After liveness and face match complete |
Async downstream |
| Zoho CRM |
Lead status update |
After stage completion or drop |
Async downstream |
| CDP |
Customer data platform update |
After stage results stored |
Async downstream |
| Datalake |
Analytics event logging |
After each major step (liveness, face match, location) |
Async downstream |
13. Database Tables (New Backend)
13.1 Operational Tables
| Table | Purpose | Key Fields (Stage 7 Relevant) |
|---|
leads |
Master lead record |
state (LIVENESS_DONE / DROPPED), liveness_passed, liveness_vendor, face_match_score, stp_face_flag, selfie_path, geolocation_city, geolocation_country, aadhaar_photo_deleted_at |
liveness_verifications |
Liveness check and face match results from all vendors |
lead_id, vendor (hyperverge / ainxt), type (liveness / face_match), attempt_number, result (pass / fail), score, request_payload, response_payload, created_at |
aadhaar_verifications |
Aadhaar verification records (read for photo path) |
lead_id, aadhaar_photo_path (read at Stage 7), photo_deleted_at (written at Stage 7) |
document_path_info |
File storage path tracking for selfie and documents |
lead_id, document_type (selfie), file_path, storage_type (configured_drive), created_at |
journey_stage_events |
Stage transition audit trail |
lead_id, stage (STAGE_7), event (LIVENESS_PASSED / LIVENESS_FAILED / FACE_MATCH_STP / FACE_MATCH_NON_STP / FACE_MATCH_FAIL / LOCATION_OUTSIDE_INDIA), metadata, created_at |
downstream_events |
Async events dispatched to external systems |
lead_id, target (clevertap / zoho / datalake / cdp), event_type, status, dispatched_at |
cs_journey_holds |
Leads routed to customer support |
lead_id, hold_reason (CS_LIVENESS_DOWN / GEOCODING_FAIL), stage (STAGE_7), created_at, resolved_at |
13.2 Reference Tables
No stage-specific reference tables are required for Stage 7. Vendor configuration (Hyperverge, AiNXT) is managed via the shared provider_configurations table.
14. File Storage Note
No S3, No Redis
File storage for selfie images uses a configured drive (tracked via document_path_info table), NOT Amazon S3. There is no Redis usage in this stage. All state is managed via the database and in-memory session context.