1. Stage 5 Objective
Fetch Aadhaar data via DigiLocker: name, DOB, address, gender, photo, and father name. The Aadhaar name is matched against ekyc_name (set in Stage 4) to produce a name match score that determines STP eligibility.
UIDAI Mandate: XML Deletion Within 24 Hours
The signed Aadhaar XML received from DigiLocker must be deleted within 24 hours of receipt. This is enforced via a scheduled background job (queries document_path_info table). A P0 alert fires if deletion fails.
Photo Retention
The Aadhaar photo extracted from the XML is retained temporarily for Stage 7 (face match). After Stage 7 completes, the photo must be deleted from configured drive (path from document_path_info table). A P1 alert fires if deletion fails.
2. Preconditions
| Condition | Detail |
|---|
lead.state = PAN_VERIFIED | Lead must have completed Stage 4 (PAN verification) with state PAN_VERIFIED |
journey_path = DIGILOCKER_REQUIRED | Stage is skipped entirely if journey_path = DIGILOCKER_SKIP |
ekyc_name must be set | The ekyc_name field must have been populated during Stage 4. This is the name that Aadhaar name will be matched against. |
Skip Condition
If journey_path = DIGILOCKER_SKIP, this entire stage is bypassed. The lead transitions directly from PAN_VERIFIED to the next applicable stage. See the decision table below for when this occurs.
3. When Is This Stage Required?
The decision to require or skip DigiLocker depends on the KRA status (from Stage 2 background checks) and the usability of the address on file:
| KRA Status | Address Condition | DigiLocker Required? | Notes |
|---|
KRA_VALIDATED |
Usable address on file |
No (skipped) |
journey_path = DIGILOCKER_SKIP. KRA address is sufficient. |
KRA_VALIDATED |
Outdated address |
Yes |
journey_path = DIGILOCKER_REQUIRED. Need fresh address from Aadhaar. |
KRA_MOD |
Usable address on file |
No (skipped) |
journey_path = DIGILOCKER_SKIP. Existing address is sufficient. |
KRA_MOD |
Outdated address |
Yes |
journey_path = DIGILOCKER_REQUIRED. Need fresh address from Aadhaar. |
NON_KRA |
Any |
Yes (always) |
journey_path = DIGILOCKER_REQUIRED. No KRA data available; Aadhaar is the primary source. |
API_DOWN |
Any |
Yes (always) |
journey_path = DIGILOCKER_REQUIRED. KRA status unknown; must collect via Aadhaar. |
RESTRICTED |
N/A |
Never reached |
Journey stopped at Stage 4 with DROP_KRA_RESTRICTED. Customer never reaches Stage 5. |
4. Backend Flow — DigiLocker Path
1
DigiLocker consent stored. Record consent_digilocker_given = true, consent_digilocker_timestamp, and consent_digilocker_version in the consents table. Explicit consent is mandatory before any Aadhaar access (UIDAI requirement).
2
AiNXT generates redirect URL + session token. Call AiNXT DigiLocker API to obtain the UIDAI DigiLocker portal redirect URL and a session token for callback correlation.
3
Customer redirected to UIDAI DigiLocker portal. This is an external redirect. The customer leaves the EKYC application and authenticates directly on the UIDAI portal.
4
Customer authenticates with Aadhaar OTP. The OTP is sent to the Aadhaar-registered mobile number, which may differ from the EKYC mobile number used in Stage 2. This OTP is handled entirely by UIDAI — our backend does not see or validate it.
5
AiNXT callback receives signed Aadhaar XML. After successful authentication, AiNXT receives the signed XML document from DigiLocker and invokes our callback endpoint with the parsed data.
6
Extract data from XML: name, DOB, address, gender, photo, and father name (extracted from the Care Of field). Store each field in the corresponding aadhaar_verifications columns.
7
Aadhaar number masking. Only the first 4 and last 4 digits of the Aadhaar number are retained (e.g., 1234XXXX5678). The full Aadhaar number is NEVER stored in any database, log, or file.
8
Address language conversion. If the address is in a regional language, it is converted to English using AiNXT language translation API. If conversion fails, the raw regional text is stored and the record is flagged NON_STP.
9
Name match against ekyc_name. The extracted Aadhaar name is compared against ekyc_name (from Stage 4) using Claude API or AiNXT name matching service. Returns a score from 0 to 100.
10
XML scheduled for 24-hour deletion. The Aadhaar XML is stored on configured drive (path from document_path_info table) and a scheduled background job deletes it within 24 hours (UIDAI mandate). The photo is stored separately on configured drive (path from document_path_info table) with a temporary reference for use at Stage 7 (face match).
Aadhaar OTP vs. EKYC OTP
The Aadhaar OTP sent by UIDAI goes to the customer's Aadhaar-registered mobile number. This may be a different number than the one used for EKYC registration (Stage 1/2). Our backend has no visibility into or control over this OTP.
5. Aadhaar Name Match Scoring
The name match score determines whether the journey proceeds in STP (straight-through processing) mode, requires ops review, or is permanently dropped:
| Score Range | stp_aadhaar_flag | Journey Impact | Notes |
|---|
70 – 100 |
STP |
Journey continues normally |
High-confidence match. No manual review needed. |
1 – 69 |
NON_STP |
Journey continues (ops review queued) |
Low-confidence match. Operations team reviews the name mismatch. Customer is not blocked. |
0 |
N/A |
Permanent stop — DROP_DL_NAME_FAIL |
Complete mismatch. Lead is dropped. Journey is terminated. |
Score 0 = Permanent Drop
A name match score of 0 results in DROP_DL_NAME_FAIL. This is a permanent journey termination. The customer cannot proceed and must restart with correct documentation.
6. Aadhaar Upload Fallback
6.1 Triggers for Fallback
- DigiLocker unreachable — CS (Customer Service) Journey when DigiLocker service is down
- 3 failed OTP attempts — Customer exhausts Aadhaar OTP attempts on the UIDAI portal
- Customer chooses upload — Customer voluntarily opts for manual upload instead of DigiLocker
6.2 Upload Specifications
| Parameter | Value | Notes |
|---|
| Accepted formats |
JPG, PNG, PDF |
Validated on backend. Other formats rejected with FE_DL_001. |
| Max file size |
5 MB |
Exceeding limit returns FE_DL_002. |
| Document required |
Front of Aadhaar card |
Must contain name, DOB, address, photo, and Aadhaar number. |
| Empty file check |
File size > 0 bytes |
Empty files rejected with FE_DL_003. |
6.3 Upload Processing
1
File uploaded to configured drive. The document is stored on configured drive (path from document_path_info table) with the lead-specific reference in the document_uploads table.
2
AiNXT OCR extracts data. The uploaded image/PDF is sent to AiNXT OCR service to extract name, DOB, address, gender, photo, and Aadhaar number.
3
Aadhaar number masking applied. Same masking rules as DigiLocker path — only first 4 and last 4 digits retained.
4
Name match scoring. Same Claude API / AiNXT name matching as DigiLocker path.
OCR Failure Handling
If AiNXT OCR fails to extract data from the uploaded document, the raw image/PDF is stored for manual verifier review. The record is automatically flagged as NON_STP. The journey continues but requires ops intervention.
Password-Protected PDFs
Password-protected PDF files cannot be processed by OCR. These are rejected with an error message prompting the customer to upload an unprotected version.
7. Backend Validations
| Check | Condition | Result | Severity |
|---|
| Name match score = 0 |
Aadhaar name vs ekyc_name score is exactly 0 |
DROP_DL_NAME_FAIL — permanent journey stop |
P0 — journey terminated |
| XML missing photo |
DigiLocker XML does not contain a photo element |
Flag as NON_STP. Journey continues, ops review queued. |
P2 |
| Address fields empty |
Aadhaar XML/OCR returns empty or null address fields |
Flag as NON_STP. Journey continues, ops review queued. |
P2 |
| Language conversion failure |
Regional language address cannot be translated to English |
Raw regional text stored. Flag as NON_STP. |
P2 |
| File storage failure |
Failed to store XML, photo, or uploaded document on configured drive |
P1 alert fired. Retry with exponential backoff. If persistent, escalate to infrastructure team. |
P1 |
| DigiLocker attempt 1–2 fails |
Customer fails authentication on DigiLocker portal (1st or 2nd attempt) |
Allow retry. Customer is redirected to DigiLocker again. |
P3 |
| DigiLocker 3rd attempt fails |
Customer fails authentication on 3rd attempt |
Trigger upload fallback. Customer is prompted to upload Aadhaar card instead. |
P2 |
| Password-protected PDF |
Uploaded PDF is password-protected and cannot be read by OCR |
Return error. Prompt customer to upload an unprotected file. |
P3 |
8. UIDAI Compliance Rules (NON-NEGOTIABLE)
These rules are mandated by UIDAI and are legally binding. Non-compliance can result in license revocation and legal action.
| Rule | Implementation | Enforcement | Alert Level |
|---|
| XML deleted within 24 hours |
Scheduled background job deletes files from configured drive. Job queries document_path_info WHERE FileType='AADHAAR_XML' AND CreatedAt < 24 hours ago AND IsDeleted=false. |
Scheduled background job runs periodically. Monitoring job verifies deletion. If XML exists beyond 24 hours, alert fires. |
P0 |
| Photo deleted after Stage 7 face match |
Scheduled background job or explicit deletion trigger after Stage 7 completion. File path from document_path_info table. |
Stage 7 completion handler triggers photo deletion from configured drive. Monitoring verifies removal. |
P1 |
| Aadhaar number NEVER stored in full |
Masking applied before any write operation — first 4 + last 4 digits only |
Application-level masking. No full Aadhaar number in DB, logs, file storage, or any downstream system. |
P0 |
| Explicit consent before Aadhaar access |
Consent recorded in consents table before DigiLocker redirect or upload |
Backend validates consent record exists before initiating any Aadhaar-related API call. |
P0 |
| Only UIDAI-certified ASAs/AUAs used |
All Aadhaar operations routed through AiNXT (certified ASA/AUA) |
No direct Aadhaar API calls. All interactions via certified intermediary. |
P0 |
9. Existing SP Mapping
9.1 Stored Procedures (Old System)
These stored procedures from the legacy system map to Stage 5 functionality. They serve as reference for what the new backend must replicate:
| Stored Procedure | Purpose |
|---|
USP_INSERT_AINXT_DIGILOCKER_REQUEST_SJET |
DigiLocker request logging — records the outbound request to AiNXT DigiLocker API |
USP_INSERT_AINXT_DIGILOCKER_RESPONSE_SJET |
DigiLocker response logging — records the inbound response/callback from AiNXT |
USP_CHECKPANNO_DIGILOCKER_SJET |
PAN match validation via DigiLocker — cross-checks PAN data from DigiLocker with existing records |
USP_CHECK_AINXT_DIGILOCKER_ADDR_EXISTS_SJET |
Address existence check — verifies if a valid address was extracted from DigiLocker data |
USP_CHECKAADHARMISMATCHXML_SJET |
Aadhaar XML mismatch check — detects discrepancies in Aadhaar XML data |
USP_AADHAR_RESPONSE_LOG_SJET |
Aadhaar response logging — logs all Aadhaar verification response data |
USP_INSERT_OCR_AMAZON_AADHAR_RESPONSE |
OCR Aadhaar response storage — stores OCR extraction results from uploaded Aadhaar documents |
9.2 Old External API Calls
Legacy API methods that the new backend must integrate with (or replace):
| Old API | Vendor | Purpose |
|---|
DigilockerAPI |
AiNXT |
Redirect URL generation, XML parsing, document download from DigiLocker |
AadhaarAPI |
AiNXT / UIDAI |
Aadhaar verification and data retrieval |
NameMatchingAPI |
AiNXT |
Name match scoring between Aadhaar name and ekyc_name |
9.3 Old Reference Tables
Legacy database tables referenced by the old stored procedures:
| Table | Purpose |
|---|
TBL_AINXT_DIGILOCKER_REQ_DETAILS |
Request logs for DigiLocker API calls |
TBL_AINXT_DIGILOCKER_RESPONSE_DETAILS |
Response logs for DigiLocker API callbacks |
TBL_CLIENT_AADHAARDTAILS |
Aadhaar data storage (name, DOB, address, gender, photo reference) |
TBL_CLIENT_DIGILOCKER_AADHAARPAN_DETAILS |
DigiLocker-extracted Aadhaar and PAN cross-reference data |
TBL_OAO_DETAILS |
Key columns: ISDIGILOCKER_PAN (DigiLocker PAN flag), AADHARXML_STATUS (XML processing status) |
10. Error / Drop Codes
| Code | Type | Trigger | User Impact |
|---|
DROP_DL_NAME_FAIL |
Drop |
Aadhaar name match score = 0 against ekyc_name |
lead.state = DROPPED. Journey permanently terminated. Customer must restart. |
CS_DIGILOCKER_DOWN |
CS Hold |
DigiLocker service is unreachable or returning errors |
Customer placed on CS Journey hold. Upload fallback offered when service is down. |
FE_DL_001 |
Frontend Error |
Uploaded file type is not JPG, PNG, or PDF |
Show error: unsupported file format. Customer must upload a valid file type. |
FE_DL_002 |
Frontend Error |
Uploaded file exceeds 5 MB size limit |
Show error: file too large. Customer must upload a smaller file. |
FE_DL_003 |
Frontend Error |
Uploaded file is empty (0 bytes) |
Show error: empty file. Customer must upload a valid document. |
11. Exit State
After Stage 5 completes (DigiLocker authentication or Aadhaar upload processed), the following fields are populated:
| Field | Value / Source | Notes |
|---|
lead.state |
DIGILOCKER_DONE |
Set after successful data extraction and name match scoring |
digilocker_method |
DIGILOCKER | UPLOAD |
Indicates whether data was fetched via DigiLocker or manual upload |
aadhaar_name |
Name from Aadhaar XML / OCR |
Full name as it appears on Aadhaar |
aadhaar_dob |
DOB from Aadhaar XML / OCR |
Date of birth as it appears on Aadhaar |
aadhaar_address_* |
Address fields from Aadhaar XML / OCR |
Structured address fields (line1, line2, city, state, pincode). Translated to English if originally in regional language. |
aadhaar_gender |
Gender from Aadhaar XML / OCR |
As recorded on Aadhaar (M / F / T) |
aadhaar_photo_path |
File path (from document_path_info.physical_path) for the extracted photo |
Temporary. Retained only until Stage 7 face match. Deleted from configured drive after Stage 7 completes. |
father_name |
Extracted from Aadhaar Care Of field |
Father's name as derived from the "C/O" or "S/O" field in the Aadhaar XML |
aadhaar_name_match_score |
0 – 100 |
Score from Claude API / AiNXT name matching service |
stp_aadhaar_flag |
STP | NON_STP |
Based on name match score: 70-100 = STP, 1-69 = NON_STP, 0 = dropped |
consent_digilocker_version |
Version string of consent text |
Tracks which version of the consent language was presented and accepted |
aadhaar_xml_deletion_scheduled_at |
Timestamp (UTC) |
When the scheduled background job deletion is expected. Must be within 24 hours of XML receipt. |
Successful Exit
On successful completion, the lead transitions to DIGILOCKER_DONE with all Aadhaar data fields populated, name match score calculated, and XML deletion tracked via document_path_info table for scheduled background job processing.
12. Vendor Calls
| Vendor / System | Purpose | When Called |
|---|
| AiNXT DigiLocker |
Generate redirect URL, session token, receive callback with signed XML |
DigiLocker consent given, customer initiates DigiLocker flow |
| UIDAI Portal |
Customer-facing Aadhaar authentication (OTP on Aadhaar-registered mobile) |
Customer redirected from EKYC app to UIDAI |
| AiNXT XML Parse |
Parse signed Aadhaar XML to extract structured data fields |
After DigiLocker callback with XML |
| AiNXT OCR |
Extract data from uploaded Aadhaar card image/PDF |
Upload fallback path — after customer uploads Aadhaar document |
| AiNXT Translation |
Regional language to English address translation via AiNXT language translation API |
When Aadhaar address contains non-English text |
| Claude API / AiNXT |
Name match scoring (Aadhaar name vs. ekyc_name) |
After Aadhaar data extraction (both DigiLocker and upload paths) |
| File Storage (Configured Drive) |
Files stored on configured network/local drive. Paths managed via document_path_info DB table. |
After data receipt from DigiLocker callback or document upload |
| Scheduled Deletion Job |
Deletes Aadhaar XML after 24 hours, photo after Stage 7. Uses document_path_info table for tracking. |
Background job runs periodically to enforce UIDAI deletion mandates |
| CleverTap |
Event tracking (DigiLocker initiated, completed, upload, name match result) |
After each significant event in the stage |
| Zoho CRM |
Lead status update with Aadhaar verification result |
After stage completion |
| CDP |
Customer data platform update with Aadhaar-sourced data |
After Aadhaar data extraction and storage |
| Datalake |
Analytics event logging for DigiLocker/Aadhaar verification events |
After each significant event in the stage |
13. Database Tables
13.1 Operational Tables
| Table | Purpose | Key Fields (Stage 5 Relevant) |
|---|
leads |
Master lead record |
state (DIGILOCKER_DONE / DROPPED), journey_path, stp_aadhaar_flag, aadhaar_name_match_score |
aadhaar_verifications |
Aadhaar data extracted from DigiLocker or upload |
lead_id, method (DIGILOCKER / UPLOAD), aadhaar_name, aadhaar_dob, aadhaar_address_*, aadhaar_gender, father_name, aadhaar_photo_path, aadhaar_masked, name_match_score, xml_deletion_scheduled_at |
consents |
Consent records for regulatory compliance |
lead_id, consent_type (DIGILOCKER), given, timestamp, version |
journey_stage_events |
Stage transition audit trail |
lead_id, stage (STAGE_5), event (DIGILOCKER_INITIATED / DIGILOCKER_COMPLETED / UPLOAD_COMPLETED / NAME_MATCH_FAILED), 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 |
Customer service journey holds when DigiLocker is down |
lead_id, hold_reason (CS_DIGILOCKER_DOWN), created_at, resolved_at |
document_uploads |
Uploaded Aadhaar card documents (fallback path) |
lead_id, document_type (AADHAAR_FRONT), file_path (from document_path_info.physical_path), file_type, file_size, ocr_status, created_at |
13.2 Reference Tables
No Stage-Specific Reference Tables
Stage 5 does not require any dedicated reference tables. All configuration (scheduled deletion job settings, name match thresholds, file size limits) is managed via application configuration and environment variables. File paths are tracked in the document_path_info table.