Flutter SDK - Quick Start Guide

The following guide helps you integrate the HyperKYC Flutter 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 Flutter SDK quickly.

Step 1: Add SDK to Your Project

Install the Flutter plugin using pub:

Bash

# Install the Flutter plugin
flutter pub add hyperkyc_flutter

Platform-Specific Installation

Android: Ensure minimum SDK version is 21 or higher in android/app/build.gradle. Add the HyperVerge Maven repository in android/build.gradle (see Integration Guide for details).

iOS: Install native dependencies:

cd ios && pod install && cd ..

For detailed platform configuration including permissions and repository setup, see the Integration Guide.

Step 2: Initialize and Launch the SDK

Initialize the SDK and launch a verification workflow in your Flutter app:

The following integration code creates a configuration instance based on the accessToken:

Dart

var hyperKycConfig = HyperKycConfig.fromAccessToken(
    accessToken: "<access-token>", // Refer to the "Authentication" page
    workflowId: "<workflow-id>",
    transactionId: "<transaction-id>",
);

// Launch the HyperVerge SDK with configuration
try {
  HyperKycResult hyperKycResult = await HyperKyc.launch(
      hyperKycConfig: hyperKycConfig
  );
  
  // Handle verification outcome
  String? status = hyperKycResult.status?.value;
  switch (status) {
    case 'auto_approved':
      // All checks passed - update UI, proceed
      print('Workflow successful - auto approved');
      break;
    case 'auto_declined':
      // Verification failed - show rejection UI
      print('Workflow successful - auto declined');
      break;
    case 'needs_review':
      // Ambiguous result - show pending review UI
      print('Workflow successful - needs review');
      break;
    case 'user_cancelled':
      // User exited flow - handle gracefully
      print('User cancelled the workflow');
      break;
    case 'error':
      // Technical failure - show retry option
      print('Workflow failed with error');
      break;
  }
} catch (e) {
  print('Error launching HyperKYC: $e');
}

The following table describes each parameter in the configuration:

Parameter	Description	Source
appId & appKey	Credentials for authentication	HyperVerge Dashboard Credentials
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, language settings, platform-specific setup, and advanced configuration options.
• Error Codes & Troubleshooting: 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 Flutter 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.
• Avoid repeated SDK initialization. Ensure your app prevents multiple button presses or asynchronous triggers to avoid multiple invocations of the SDK.