BRD - Aadhaar KYC with Digilocker

1. Executive Summary

1.1 Purpose

Implement Aadhaar-based KYC verification system using Cashfree's DigiLocker integration API for user identity verification on the OX Agry platform.

1.2 Scope

Aadhaar verification via Cashfree DigiLocker API
Face matching using Cashfree's face match API
KYC data management and validity tracking
Re-KYC flow for expired verifications

1.3 Tech Stack

Backend: NestJS (existing)
Frontend: TanStack Router (existing)
Database: PostgreSQL
External API: Cashfree VRS v2 API
Storage: AWS S3 (encrypted)

2. Functional Requirements

2.1 User Flow Requirements

FR-001: Display KYC information and benefits
FR-002: Show clear privacy policy and data usage information
FR-003: Require explicit consent checkbox before proceeding
FR-004: Display text: "I consent to KYC verification via DigiLocker"
FR-005: Show security assurance: "Your data is encrypted and secure as per UIDAI guidelines"
FR-006: Button text: "Proceed with DigiLocker" (disabled until consent given)

2.1.2 Create DigiLocker URL (Cashfree API)

FR-007: Call Cashfree Create URL API with document_requested=["AADHAAR"]
FR-008: Set user_flow="signup" by default (or "signin" for re-KYC)
FR-009: Generate unique reference_id for tracking
FR-010: Receive and store DigiLocker redirect URL
FR-011: Set redirect_url to app callback endpoint
FR-012: Handle API errors with user-friendly messages

2.1.3 DigiLocker Redirect & Authentication

FR-013: Redirect user to Cashfree-generated DigiLocker URL
FR-014: User enters Aadhaar number on DigiLocker portal (not in our app)
FR-015: User authenticates with Aadhaar credentials
FR-016: User enters OTP provided by UIDAI
FR-017: User gives consent to Cashfree to fetch Aadhaar details
FR-018: Handle user cancellation (redirect back to consent screen)

2.1.4 Webhook Processing (Cashfree Callback)

FR-017: Receive webhook from Cashfree with verification status
FR-018: Validate webhook signature for security
FR-019: Process SUCCESS response → Extract user data and photo
FR-020: Process FAILURE response → Show error message
FR-021: Store Aadhaar data temporarily in encrypted format
FR-022: Navigate to selfie capture on success

2.1.5 Selfie Capture

FR-023: Show selfie capture screen with instructions
FR-024: Display: "Ensure good lighting", "Remove glasses if possible", "Keep face centered"
FR-025: Capture selfie using device camera
FR-026: Convert image to base64 format
FR-027: Show preview with retake option
FR-028: Maximum 3 selfie attempts allowed

2.1.6 Face Matching (Cashfree API)

FR-029: Call Cashfree Face Match API with two images
FR-030: Image 1: Aadhaar photo from DigiLocker response
FR-031: Image 2: Captured selfie
FR-032: Require minimum 80% match score for approval
FR-033: Show appropriate message based on match result
FR-034: After 3 failed attempts → Flag for manual review

2.1.7 KYC Status Management

FR-035: On successful face match → Mark KYC as VERIFIED
FR-036: Set validity period to 10 years from verification date
FR-037: Generate unique KYC reference number
FR-038: Enable all platform features
FR-039: Send confirmation notification (SMS/Email/In-app)

2.1.8 Verification Details Screen

FR-040: Show document details section (if verified)
FR-041: Display timeline with verification steps status
FR-042: For failed verification: Hide document, show "Retake Selfie" button
FR-043: For success: Show document, show "Reverify" button
FR-044: Reverify button pre-fills Aadhaar and restarts process

2.1.9 Manual Review Flow

FR-045: After 3 failed selfie attempts → Update status to "Manual Review"
FR-046: Send notification to admin dashboard
FR-047: Show user: "Verification under review (24 hours)"
FR-048: Admin can approve/reject from dashboard

2.1.10 Re-KYC Flow

FR-049: Check KYC expiry date on user login
FR-050: Show reminder 60, 30, 7 days before expiry
FR-051: Pre-fill Aadhaar number from previous KYC
FR-052: Restart verification with Create URL API (action="signin")

3. Non-Functional Requirements

3.1 Performance

NFR-001: Complete KYC flow in under 3 minutes
NFR-002: API response time < 2 seconds (excluding Cashfree APIs)
NFR-003: Support 1000 concurrent KYC sessions
NFR-004: Webhook processing < 1 second

3.2 Security

NFR-005: Verify Cashfree webhook signatures
NFR-006: Encrypt stored Aadhaar data using AES-256
NFR-007: Store only masked Aadhaar (XXXX-XXXX-1234)
NFR-008: Delete full Aadhaar data after verification
NFR-009: Use HTTPS for all API communications
NFR-010: Implement request signing for Cashfree APIs

3.3 Compliance

NFR-011: Follow UIDAI rate limits (5 attempts per day)
NFR-012: Comply with RBI KYC guidelines
NFR-013: Maintain audit logs for all KYC operations
NFR-014: Store KYC records for regulatory period

3.4 Reliability

NFR-015: Implement webhook retry mechanism
NFR-016: Handle Cashfree API timeouts gracefully
NFR-017: Queue failed webhooks for reprocessing
NFR-018: Fallback to manual review if APIs fail

4. Environment Configuration

# Cashfree Configuration
CASHFREE_CLIENT_ID=your_client_id
CASHFREE_CLIENT_SECRET=your_client_secret
CASHFREE_WEBHOOK_SECRET=your_webhook_secret
CASHFREE_ENV=sandbox # or production

# Application URLs
APP_URL=https://app.oxagry.com
WEBHOOK_URL=https://app.oxagry.com/api/webhooks/cashfree/digilocker

# Security
ENCRYPTION_KEY=your_32_character_encryption_key
JWT_SECRET=your_jwt_secret

# Rate Limits (UIDAI Standard)
MAX_AADHAAR_ATTEMPTS_PER_DAY=5
MAX_DEVICE_ATTEMPTS_PER_DAY=10

# KYC Configuration
KYC_VALIDITY_YEARS=10
FACE_MATCH_THRESHOLD=80
MAX_SELFIE_ATTEMPTS=3

# AWS S3 (for document storage)
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=ap-south-1
AWS_S3_BUCKET=oxagry-kyc-documents

// Metrics to track
interface KYCMetrics {
  // Success rates
  digilockerSuccessRate: number; // Target: > 90%
  faceMatchSuccessRate: number; // Target: > 80%
  overallKYCSuccessRate: number; // Target: > 75%

  // Performance
  avgCompletionTime: number; // Target: < 180 seconds
  webhookProcessingTime: number; // Target: < 1 second

  // Failures
  failureReasons: {
    userCancelled: number;
    faceMatchFailed: number;
    technicalError: number;
    rateLimitExceeded: number;
  };

  // Volume
  dailyKYCAttempts: number;
  manualReviewQueue: number;
}

5. Error Handling

enum KYCErrorCodes {
  // Input Validation
  INVALID_AADHAAR = "E001",
  CONSENT_REQUIRED = "E002",

  // Rate Limiting
  DAILY_LIMIT_EXCEEDED = "E003",

  // Cashfree API
  CASHFREE_API_ERROR = "E004",
  WEBHOOK_VALIDATION_FAILED = "E005",

  // Face Matching
  FACE_MATCH_FAILED = "E006",
  MAX_ATTEMPTS_EXCEEDED = "E007",

  // Session
  SESSION_EXPIRED = "E008",
  SESSION_NOT_FOUND = "E009",
}

// User-friendly error messages
const ERROR_MESSAGES = {
  E001: "Please enter a valid 12-digit Aadhaar number",
  E002: "Please provide consent to proceed",
  E003: "Daily limit exceeded. Please try after 24 hours",
  E004: "Verification service unavailable. Please try again",
  E005: "Security validation failed",
  E006: "Face verification failed. Please try again",
  E007: "Maximum attempts exceeded. Manual review required",
  E008: "Session expired. Please start again",
  E009: "Session not found. Please restart verification",
};

6. Deployment Checklist

Pre-Production

Production

Switch Cashfree from sandbox to production
Update API URLs to production endpoints
Enable production webhook secret
Configure monitoring and alerts
Set up backup for KYC data
Security audit completed
Load testing performed
Support team trained
User documentation ready

7. Timeline

Phase	Tasks	Duration
Phase 1	Cashfree integration setup	1 days
Phase 2	Backend APIs development	2 days
Phase 3	Frontend screens	1 day
Phase 4	Webhook handling & testing
Phase 5	Face matching integration
Phase 6	Manual review flow
Phase 7	End-to-end testing
Phase 8	Security audit & fixes
Phase 9	UAT & deployment

Document End

For Cashfree API support: https://www.cashfree.com/docs/api-reference/vrs/v2/digilocker/digilocker-integration

1. Executive Summary
2. Functional Requirements
- 2.1 User Flow Requirements
3. Non-Functional Requirements
4. Environment Configuration
5. Error Handling
6. Deployment Checklist
- Pre-Production
- Production
7. Timeline

1. Executive Summary​

1.1 Purpose​

1.2 Scope​

1.3 Tech Stack​

2. Functional Requirements​

2.1 User Flow Requirements​

2.1.1 KYC Consent Screen​

2.1.2 Create DigiLocker URL (Cashfree API)​

2.1.3 DigiLocker Redirect & Authentication​

2.1.4 Webhook Processing (Cashfree Callback)​

2.1.5 Selfie Capture​

2.1.6 Face Matching (Cashfree API)​

2.1.7 KYC Status Management​

2.1.8 Verification Details Screen​

2.1.9 Manual Review Flow​

2.1.10 Re-KYC Flow​

3. Non-Functional Requirements​

3.1 Performance​

3.2 Security​

3.3 Compliance​

3.4 Reliability​

4. Environment Configuration​

5. Error Handling​

6. Deployment Checklist​

Pre-Production​

Production​

7. Timeline​

1. Executive Summary

1.1 Purpose

1.2 Scope

1.3 Tech Stack

2. Functional Requirements

2.1 User Flow Requirements

2.1.1 KYC Consent Screen

2.1.2 Create DigiLocker URL (Cashfree API)

2.1.3 DigiLocker Redirect & Authentication

2.1.4 Webhook Processing (Cashfree Callback)

2.1.5 Selfie Capture

2.1.6 Face Matching (Cashfree API)

2.1.7 KYC Status Management

2.1.8 Verification Details Screen

2.1.9 Manual Review Flow

2.1.10 Re-KYC Flow

3. Non-Functional Requirements

3.1 Performance

3.2 Security

3.3 Compliance

3.4 Reliability

4. Environment Configuration

5. Error Handling

6. Deployment Checklist

Pre-Production

Production

7. Timeline