This codelab introduces Identity Verification (IDV) concepts using the cordova RdnaClient plugin. You'll learn how the IDV SDK's challenge-response system works, understand different verification workflows, and master the terminology needed for implementing secure identity verification.

What You'll Learn

What You'll Need

The RELID IDV SDK implements Identity Verification through a challenge-response mechanism. This system ensures secure, step-by-step verification of user identity through document scanning, facial recognition, and biometric storage.

Core IDV Concepts

Challenge-Response Pattern

The IDV system works on a fundamental challenge-response pattern:

  1. Plugin/SDK Issues Challenge: The Plugin/SDK identifies what verification step it needs
  2. Event Triggered: Your app receives an event via DOM event listener
  3. User Interaction: App collects required information or captures biometric data
  4. API Response: App responds with appropriate API call
  5. Flow Continuation: Plugin/SDK processes response and continues or completes flow

IDV Flow Initialization

Identity verification can be triggered in multiple scenarios:

Activation Flow → Document Scan Challenge → IDV Flow Begins
Post-Login → Activated Customer KYC API → IDV Flow Begins
Post-Login → Additional Document Scan API → Document Capture Flow

Challenge Categories

The IDV system uses several categories of challenges:

Category

Purpose

Examples

Document Verification

Capture and verify identity documents

getIDVDocumentScanProcessStartConfirmation

Document Confirmation

Verify extracted document details

getIDVConfirmDocumentDetails

Selfie Capture

Capture user's facial biometric

getIDVSelfieProcessStartConfirmation

Facial Matching

Compare document photo with selfie

getIDVSelfieConfirmation

Biometric Storage

Opt-in for biometric template storage

getIDVBiometricOptInConsent

Event-Driven Architecture

The IDV system is completely event-driven:

The RELID IDV SDK supports multiple distinct verification workflows, each designed for specific use cases and user scenarios. These workflows range from initial onboarding with identity verification to post-login biometric management and step-up authentication.

1. Activation Flow with IDV

Purpose: First-time user registration with identity verification

When Used:

Key Characteristics:

Typical Flow Sequence:

  1. getIDVDocumentScanProcessStartConfirmation → Document capture initiated
  2. getIDVConfirmDocumentDetails → User confirms extracted data
  3. getIDVSelfieProcessStartConfirmation → Selfie capture initiated
  4. getIDVSelfieConfirmation → User confirms facial match result
  5. getIDVBiometricOptInConsent → User opts in/out for biometric storage
  6. onUserLoggedIn → Activation complete with IDV

Flow Outcome: User registered with verified identity and optional biometric template stored

2. Activated Customer KYC (Post-Login)

Purpose: Complete KYC verification for already activated users

When Used:

Key Characteristics:

Typical Flow Sequence:

  1. App calls initiateActivatedCustomerKYC(reason)
  2. getIDVDocumentScanProcessStartConfirmation → Document capture
  3. getIDVConfirmDocumentDetails → Confirm extracted data
  4. getIDVSelfieProcessStartConfirmation → Selfie capture
  5. getIDVSelfieConfirmation → Confirm facial match
  6. getIDVBiometricOptInConsent → Biometric storage consent
  7. onIDVActivatedCustomerKYCResponse → KYC completion result

Flow Outcome: User's identity verified with optional biometric template storage

3. Additional Document Scan (Post-Login)

Purpose: Scan additional documents for existing users

When Used:

Key Characteristics:

Typical Flow Sequence:

  1. App calls initiateIDVAdditionalDocumentScan(reason)
  2. getIDVDocumentScanProcessStartConfirmation → Document capture
  3. onIDVAdditionalDocumentScan → Document scan result

Flow Outcome: Additional document captured and verified

4. Biometric Opt-In Flow (Post-Login)

Purpose: Enable users to opt-in for biometric template storage after initial registration

When Used:

Key Characteristics:

Typical Flow Sequence:

  1. App calls initiateIDVBiometricOptIn()
  2. User authenticates (LDA/biometric or password based on login method)
  3. SDK initiates selfie capture for biometric template
  4. onIDVOptInCapturedFrameConfirmation → User confirms captured selfie
  5. App calls setIDVBiometricOptInConfirmation(status) with user decision
  6. onIDVBiometricOptInStatus → Opt-in completion result

Flow Outcome: User's biometric template stored on server for future passwordless authentication

API Call Example:

// Initiate biometric opt-in
com.uniken.rdnaplugin.RdnaClient.initiateIDVBiometricOptIn(
  function(response) {
    // SDK handles authentication and selfie capture
  },
  function(error) {
    console.error('Opt-in initiation failed:', error);
  }
);

// Confirm captured selfie
com.uniken.rdnaplugin.RdnaClient.setIDVBiometricOptInConfirmation(
  function(response) {
    // Handle response
  },
  function(error) {
    console.error('Confirmation failed:', error);
  },
  [RDNAIDVStatus.CONTINUE]  // or CANCEL, RECAPTURE
);

5. Biometric Opt-Out Flow (Post-Login)

Purpose: Allow users to delete their stored biometric template from the server

When Used:

Key Characteristics:

Typical Flow Sequence:

  1. App calls initiateIDVBiometricOptOut()
  2. User authenticates (LDA/biometric or password based on login method)
  3. SDK proceeds with template deletion on server
  4. onIDVBiometricOptOutStatus → Opt-out completion result

Flow Outcome: User's biometric template deleted from server

API Call Example:

// Initiate biometric opt-out
com.uniken.rdnaplugin.RdnaClient.initiateIDVBiometricOptOut(
  function(response) {
    // SDK handles authentication and template deletion
  },
  function(error) {
    console.error('Opt-out initiation failed:', error);
  }
);

Important Notes:

6. Server Biometric Authentication Flow (Post-Login)

Purpose: Authenticate users using their stored biometric template for step-up authentication

When Used:

Key Characteristics:

Typical Flow Sequence:

  1. App calls initiateIDVServerBiometricAuthentication(reason)
  2. SDK captures user selfie with liveness detection
  3. Selfie sent to server for comparison with stored template
  4. onIDVServerBiometricAuthenticationResult → Authentication result with match score

Flow Outcome: User authenticated via biometric matching; transaction/operation can proceed

API Call Example:

// Initiate server biometric authentication
com.uniken.rdnaplugin.RdnaClient.initiateIDVServerBiometricAuthentication(
  function(response) {
    // Handle sync response
  },
  function(error) {
    console.error('Authentication initiation failed:', error);
  },
  ["Verify identity for transaction"]  // reason
);

Response Data Structure:

The onIDVServerBiometricAuthenticationResult event provides:

Important Notes:

7. Step-Up Authentication Flow (Post-Login)

Purpose: Perform enhanced authentication for sensitive operations

When Used:

Key Characteristics:

Typical Use Cases:

Flow Outcome: User authenticated at higher assurance level for sensitive operation

8. Step-Up Authentication with Data Signing Flow (Post-Login)

Purpose: Perform step-up authentication combined with cryptographic data signing

When Used:

Key Characteristics:

Typical Use Cases:

Flow Outcome: User authenticated and transaction data cryptographically signed

Each IDV challenge follows a consistent event → API response pattern. Understanding these mappings is crucial for implementing verification flows.

Universal Challenge Pattern

Every challenge in the IDV system follows this pattern:

Plugin/SDK Challenge Event → App UI Interaction → API Response → Flow Continuation

Core Challenge Mappings

1. Document Scan Initiation Challenge

Challenge Name

IDV-Document-Scan-Confirmation

Event Name

getIDVDocumentScanProcessStartConfirmation

API Name

setIDVDocumentScanProcessStartConfirmation

Purpose

Initiate document capture process

When Triggered

Start of IDV workflow requiring document verification

User Input

User consent to begin document scanning

Flow Pattern:

Plugin/SDK → getIDVDocumentScanProcessStartConfirmation event → App shows info screen → User taps proceed → setIDVDocumentScanProcessStartConfirmation API → Document capture UI

Important Notes:

API Call Example:

com.uniken.rdnaplugin.RdnaClient.setIDVDocumentScanProcessStartConfirmation(
  function(response) {
    // Handle response
  },
  function(error) {
    console.error('Document scan confirmation failed:', error);
  },
  [true, idvWorkflow]  // isConfirm: true to proceed, false to cancel; idvWorkflow from event
);

2. Document Details Confirmation Challenge

Challenge Name

IDV-Confirm-Document-Details

Event Name

getIDVConfirmDocumentDetails

API Name

setIDVConfirmDocumentDetails

Purpose

Verify extracted document data with user

When Triggered

After successful document scan

User Input

User confirmation of extracted OCR data

Flow Pattern:

Document scan complete → getIDVConfirmDocumentDetails event → App displays extracted data → User confirms → setIDVConfirmDocumentDetails API → Next challenge

Response Data Structure: The event provides a JSON v3.0 object containing:

Important Notes:

API Call Example:

com.uniken.rdnaplugin.RdnaClient.setIDVConfirmDocumentDetails(
  function(response) {
    // Handle response
  },
  function(error) {
    console.error('Document details confirmation failed:', error);
  },
  [true, challengeMode]  // isConfirm: true to accept, false to rescan; challengeMode from event
);

3. Selfie Capture Initiation Challenge

Challenge Name

IDV-Selfie-Confirmation

Event Name

getIDVSelfieProcessStartConfirmation

API Name

setIDVSelfieProcessStartConfirmation

Purpose

Initiate selfie capture with liveness detection

When Triggered

After document details confirmation

User Input

User consent to capture selfie

Flow Pattern:

Plugin/SDK → getIDVSelfieProcessStartConfirmation event → App shows info screen → User taps proceed → setIDVSelfieProcessStartConfirmation API → Selfie capture UI

Important Notes:

API Call Example:

com.uniken.rdnaplugin.RdnaClient.setIDVSelfieProcessStartConfirmation(
  function(response) {
    // Handle response
  },
  function(error) {
    console.error('Selfie process confirmation failed:', error);
  },
  [true, false, idvWorkflow]  // isConfirm, useDeviceBackCamera, idvWorkflow from event
);

4. Selfie Match Confirmation Challenge

Challenge Name

IDV-Selfie-Match-Confirmation

Event Name

getIDVSelfieConfirmation

API Name

setIDVSelfieConfirmation

Purpose

Confirm facial matching result

When Triggered

After selfie capture and server-side facial matching

User Input

User decision based on match result

Flow Pattern:

Selfie captured → Server facial matching → getIDVSelfieConfirmation event → App displays match result → User selects action → setIDVSelfieConfirmation API → Flow continues

Response Data Structure:

The event provides JSON containing:

Action Options:

Important Notes:

API Call Example:

com.uniken.rdnaplugin.RdnaClient.setIDVSelfieConfirmation(
  function(response) {
    // Handle response
  },
  function(error) {
    console.error('Selfie confirmation failed:', error);
  },
  ["continue-flow", challengeMode]  // action from action_buttons, challengeMode from event
);

5. Biometric Opt-In Consent Challenge

Challenge Name

REL-ID-IDV-BiometricOptIN

Event Name

getIDVBiometricOptInConsent

API Name

setIDVBiometricOptInConsent

Purpose

Obtain user consent for biometric template storage

When Triggered

After successful selfie matching (in KYC flows)

User Input

User consent decision for biometric storage

Flow Pattern:

Plugin/SDK → getIDVBiometricOptInConsent event → App shows consent screen → User decides → setIDVBiometricOptInConsent API → Biometric storage/skip

Important Notes:

API Call Example:

com.uniken.rdnaplugin.RdnaClient.setIDVBiometricOptInConsent(
  function(response) {
    // Handle response
  },
  function(error) {
    console.error('Biometric opt-in consent failed:', error);
  },
  [true, challengeMode]  // isOptIn: true to save template, false to skip; challengeMode from event
);

Understanding key IDV terminology is essential for implementing and troubleshooting identity verification flows.

Identity Verification Terms

Document Verification

The process of capturing and validating an identity document (passport, driver's license, national ID) using OCR and authenticity checks.

Example: Scanning a passport to extract name, date of birth, document number, and photo.

OCR (Optical Character Recognition)

Technology that extracts text data from identity documents.

Example: Reading the MRZ (Machine Readable Zone) on a passport to extract structured data.

NFC (Near Field Communication) Scanning

Reading the RFID chip embedded in electronic passports and enhanced identity documents.

Key Points:

Liveness Detection

Technology that ensures the selfie is captured from a live person, not a photo or video.

Key Points:

Facial Matching

Comparing the photo from the identity document with the captured selfie to verify they are the same person.

Example: Match score of 0.95 indicates high confidence that document photo and selfie are the same person.

Technical Terms

Challenge

A security step that the Plugin/SDK requires the user to complete. Each challenge represents a specific verification requirement.

Example: The IDV-Document-Scan-Confirmation challenge requires the user to scan their identity document.

Event

A callback sent by the Plugin/SDK to your application when a challenge needs to be addressed. In Cordova, events are dispatched as DOM events to the document object.

Example: The getIDVDocumentScanProcessStartConfirmation event indicates the Plugin/SDK needs user consent to begin document scanning.

Cordova Event Handling:

// Register event listener
document.addEventListener('getIDVDocumentScanProcessStartConfirmation', function(event) {
  // Event data is in event.detail
  var eventData = event.detail;
  // Handle the challenge
});

API Response

The method your application calls to provide the required information for a challenge.

Example: Calling setIDVDocumentScanProcessStartConfirmation(successCb, errorCb, [true, workflow]) responds to the document scan initiation challenge.

Workflow

A complete sequence of challenges from start to successful verification.

Example: Activated Customer KYC workflow: Document scan → Confirm details → Selfie capture → Match confirmation → Biometric opt-in

Challenge Mode

An identifier indicating the current workflow context and authentication mode.

Key Points:

Workflow-Specific Terms

KYC (Know Your Customer)

Regulatory requirement to verify the identity of customers.

Key Points:

Biometric Template

Mathematical representation of facial features stored securely on the server.

Key Points:

Biometric Opt-In

User consent to store their biometric template on the server for future authentication.

Biometric Opt-Out

Process to delete a user's stored biometric template from the server.

Server Biometric Authentication

Authentication method that compares a live selfie capture with the user's stored biometric template on the server.

Key Points:

Step-Up Authentication

Enhanced authentication process requiring additional verification beyond the initial login for sensitive operations.

Key Points:

Data Signing

Cryptographic operation that creates a verifiable digital signature of transaction data using user's credentials.

Key Points:

Template Status Check

Operation to verify whether a user has a biometric template stored on the server.

Key Points:

Authenticity Checks

Validation of document security features to detect forgeries.

Examples:

Image Quality Checks

Validation of captured image quality to ensure successful processing.

Examples:

Configuration Terms

Database

Document recognition database containing information about valid identity documents worldwide.

Key Points:

IDV Config

Configuration settings for document scanning behavior.

Key Points:

Error Handling Terms

Long Error Code

Detailed numeric error code providing specific information about what went wrong.

Short Error Code

Generic error category for broad error classification.

Error String

Human-readable error message describing the issue and potential solutions.

Points to Consider for API Calls

Critical Timing Rules:

  1. Only call APIs in response to events - Never call IDV APIs without receiving the corresponding challenge event
  2. Sequential processing - Wait for current API to complete before handling next challenge
  3. No duplicate calls - Don't retry API calls unless explicitly handling errors
  4. Pass correct parameters - Always pass challengeMode or idvWorkflow received in events

Correct Flow:

getIDVDocumentScanProcessStartConfirmation event → setIDVDocumentScanProcessStartConfirmation API → wait for next event → getIDVConfirmDocumentDetails event → setIDVConfirmDocumentDetails API

Incorrect Flow:

setIDVDocumentScanProcessStartConfirmation API → getIDVDocumentScanProcessStartConfirmation event (❌ API called before event)
getIDVDocumentScanProcessStartConfirmation event → setIDVDocumentScanProcessStartConfirmation API → setIDVDocumentScanProcessStartConfirmation API (❌ duplicate API calls)

Congratulations! You've mastered the fundamentals of Identity Verification (IDV) with the RELID IDV SDK:

✅ Challenge-Response Architecture: Understanding how Plugin/SDK events map to API responses

✅ Workflow Types: 8 distinct workflows covering onboarding, KYC, biometric management, and step-up authentication

✅ Event Integration: Document scanning, confirmation, selfie capture, and biometric opt-in flows

✅ API Patterns: Proper response patterns and error handling

✅ IDV Terminology: Essential identity verification and technical concepts

✅ Best Practices: Timing, error handling, and implementation guidelines

Key Concepts Mastered

IDV Foundation Knowledge

You now understand:

Next Steps

With this foundation, you're ready for:

References