Android SDK - Quick Start Guide

The following guide helps you integrate the HyperKYC Android SDK and launch your first workflow in minutes.

Additional Resource

• Complete Sample Project: A ready to use example project with all the code you need to get started with the Android SDK quickly.

Step 1: Add SDK to Your Project

In your project-level build.gradle:

build.gradle

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url "https://s3.ap-south-1.amazonaws.com/hvsdk/android/releases" }
    }
}

In your App-level build.gradle:

build.gradle

implementation("co.hyperverge:hyperkyc:<SDK_VERSION>")

Pro-Tip

Replace <SDK_VERSION> with the latest version listed in the Android SDK Changelog.

Step 2: Initialize and Launch the SDK

Initialize the SDK and launch a verification workflow in your required Activity class:

Kotlin

val config = HyperKycConfig(
    accessToken = "<ACCESS_TOKEN>",  // Short-lived token from your backend
    workflowId = "<WORKFLOW_ID>",    // Workflow ID from HyperVerge Dashboard
    transactionId = "<TRANSACTION_ID>" // Unique identifier for this application
)

// Register callback to handle SDK result when verification completes
val hyperKycLauncher = registerForActivityResult(HyperKyc.Contract()) { result ->
    // Log result for debugging
    android.util.Log.d(
        "HyperKYC",
        "status=${result.status} code=${result.code} message=${result.message}"
    )

    // Handle verification outcome
    when (result.status) {
        "auto_approved" -> { /* All checks passed - update UI, proceed */ }
        "auto_declined" -> { /* Verification failed - show rejection UI */ }
        "needs_review" -> { /* Ambiguous result - show pending review UI */ }
        "user_cancelled" -> { /* User exited flow - handle gracefully */ }
        "error" -> { /* Technical failure - show retry option */ }
    }
}

// Launch the HyperVerge SDK with configuration
hyperKycLauncher.launch(config)

The following table describes each parameter in the configuration:

Parameter	Description	Source
accessToken	Short-lived token from your backend	Generate Access Tokens
workflowId	Workflow identifier	HyperVerge Dashboard
transactionId	Unique session identifier	Generated by your backend

That's it! You've launched your first HyperKYC workflow.

Step 3: Handle Results & Test the Flow

The callback in Step 2 returns one of these statuses:

Status	Description
auto_approved	User verified successfully
auto_declined	Application rejected automatically
needs_review	Flagged for manual review
user_cancelled	User exited before completion
error	SDK or network issue

For detailed response formats, error codes, and field descriptions, see the SDK Response documentation.

Test: Build & run your app, trigger the launcher, complete a sample journey, and check the log output to confirm integration.

Next Steps

Explore advanced capabilities:

• Additional Configurations: See the Integration Guide for detailed configuration options including prefetch, UI customization, and language settings.
• Error Codes & Troubleshooting: Refer to the FAQs for common issues and error handling. For detailed error codes and descriptions, see Error Response Details.
• Integrate Results Webhook: Receive backend updates when journeys complete using the Results Webhook API.
• Real-time Event Notifications: Track user progress with Real-time Event Notifications
• Sample Project: Download the Android Sample Project for a complete working example.

Recommendations

Follow these best practices to ensure a secure and smooth integration:

Important

• Validate camera & microphone permissions before SDK launch (if your workflow requires these)
• Do not send SDK results directly to your backend for decisioning. To avoid potential man‑in‑the‑middle (MITM) attacks, integrate the Results Webhook instead to securely receive verified outcomes from HyperVerge servers.