Android integration guide

Updated on 10.07.25

1 minute to read

Copy link

Integration steps

SEON ID Verification Android SDK is available through Maven Central Repository here. To install it, follow these steps:

If you are using Kotlin version catalogs

Add this into your project level (root) settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        ...
        mavenCentral()
    }
}

Add these lines under the proper section in the libs.versions.toml:

[versions]
...
seonIdVerification = "1.3.0"
...
[libraries]
...
seon-id-verification = { group = "io.seon.idvandroid", name = "id-verification-sdk-android", version.ref = "seonIdVerification" }

And add this into your module level (eg. app) build.gradle.kts:

dependencies {
    ...
    implementation(libs.seon.id.verification)
}

You can now run gradle sync.

If you are using older gradle dependency management

(syntax may vary for gradle or gradle.kts files)

Add this line to the project level (root) build.gradle(.kts):

allprojects {
   repositories {
       ...
       mavenCentral()
   }
}

And add this line to the module level (eg. app) build.gradle(.kts):

dependencies {
   ...
   implementation "io.seon.idvandroid:id-verification-sdk-android:1.3.0"
}

You can now run gradle sync.

To integrate the SDK first thing you have to do is init the activity result launcher (before onResume() is called), so you could do it initially in your activity:

private val activityResultLauncher =
   registerForActivityResult(StartActivityForResult()) { result: ActivityResult ->
       handleResult(result)
   }

Next thing is to initialize the SDK through IDVService class (singleton) initialize(...) method:

IDVService.instance.initialize(
   baseUrl = "https://idv-eu.seon.io", // alternatively: "https://idv-us.seon.io"
   customerData = IDVCustomerData(
     licenseKey = "YOUR_LICENSE_KEY", // use the licenseKey you received from SEON (required)
     referenceId = "UNIQUE_REFERENCE_ID", // Random unique value for the session
                                      // e.g. UUID, or {userID}-{timestamp} (required)
     email = "user@example.com",      // Email input (optional)
     name = "John Doe",               // Name input (optional)
     phoneNumber = "+1234567890",     // Phone number input (optional)
     type = "id-verification",        // Process type (optional)
     userId = "user123",              // Unique user identifier (optional)
     countryISOCode = "US",           // ISO code for the country (optional)
     address = "123 Main St, NY",     // Address input (optional)
     dateOfBirth = {                  // Reference date for the DoB check (optional)
       day = 1,
       month = 1,
       year = 2000,
     },
     postalCode = "12345",            // Reference value for postal check (optional)
     additionalProperties = {         // Custom key-value pairs (optional)
       customField1 = "value1",
       customField2 = "value2",
     },
   ),
   templateId = null, // See the templateId if you have defined a template in the admin panel (optional)
   languageCode = "en" // use the language iso code you prefer to use in the SDK. If not provided, we fall back on the default Locale language of the app, or finally on our default language, which is English (for the available languages please contact SEON)
)

For further information about the configuration, please visit the Session Input Configuration for Android.

And now you can start its verification flow by calling startVerificationFlow(...) method of the IDVService class:

IDVService.instance.startVerificationFlow(
   activityResultLauncher,
   applicationContext
)

Also you have to add these permissions and features to your app's AndroidManifest.xml file:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
   android:maxSdkVersion="28" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
   android:maxSdkVersion="32" />
<uses-feature
   android:name="android.hardware.camera"
   android:required="true" />

Lastly you have to implement the handler method called by the activityResultLauncher:

private fun handleResult(result: ActivityResult) {
   when (result.resultCode) {
       IDVFlowResult.InterruptedByUser.code -> {
           // user navigated back
       }
       IDVFlowResult.Error.code -> {
           // handle error, its code is given in the bundle under the following key
           val error = result.data?.getStringExtra(VERIFICATION_ERROR_KEY)
       }
       IDVFlowResult.Completed.code -> {
           // handle completed status
       }
       
       IDVFlowResult.CompletedSuccess.code -> {
           // handle completed success status
       }
       
       IDVFlowResult.CompletedPending.code -> {
           // handle completed pending status
       }
       
       IDVFlowResult.CompletedFailed.code -> {
           // handle completed failed status
       }
   }
}

You could also customize the SDK main colors through the IDVService class setThemeColors(...) method (the pair's first parameter is for light color, second is for dark color theme), please call it before you start the flow, but the best would be to call this even before the initialize(...) method is called

IDVService.instance.setThemeColors(
   textOnLight = Pair(getColor(R.color.black), getColor(R.color.white)),
   textOnDark = Pair(getColor(R.color.white), getColor(R.color.black)),
   accent = Pair(getColor(R.color.purple), getColor(R.color.purple)),
   onAccent = Pair(getColor(R.color.black), getColor(R.color.white)),
)

Error codes

This section describes the possible error codes returned by the SEON ID Verification Android SDK, along with suggested checks and resolutions for each case.

ERROR_CODE_1

Description: The current session is unrecoverable.

Resolution:

Start a new session by reinitializing the SDK with a fresh configuration.
Check if you have provided correct baseUrl, customerData and licenseKey (associated with correct application ID).

ERROR_CODE_2

Description: Failure in fetching session data or initializing the SDK due to missing or incorrect parameters.

Checklist for resolution:

Verify that the baseUrl is properly provided in the SDK initialization.
Confirm that the customerData is correctly set.
Check if the licenseKey is valid and correctly associated:
Ensure the licenseKey matches the application ID registered with SEON.
The application ID used in your project must be the same as the one associated with the license key on SEON’s server.
Ensure that the device has a stable internet connection.

ERROR_CODE_3

Description: The session has expired.

Typical cause: Sessions can expire if the verification flow takes an excessively long time to complete.

Resolution: Restart the verification by creating a new session.

ERROR_CODE_4

Description: The provided license key is invalid.

Resolution:

Verify that the licenseKey entered is correct.
Ensure the license key is active and has not been revoked or misconfigured.

ERROR_CODE_5

Description: Retry limit reached during document capture.

Typical cause: The user has failed document capture attempts more than the allowed number of retries.

Resolution: Restart the verification process by initiating a new session.

ERROR_CODE_6

Description: Retry limit reached during the liveness verification step.

Typical cause: The user has exceeded the maximum allowed number of retries for the liveness verification check.

Resolution: Restart the verification process by initiating a new session.