Check-Driven Integration

Integrate the Android SDK using a check-driven approach.

Overview

This guide walks you through integrating the Android SDK with ComplyCube using the check-driven approach, giving you direct control over individual verification steps.

Mobile SDK View

You’re viewing the check-driven SDK guide - an approach that provides detailed control but is best suited for partners or advanced use cases. We recommend using workflow integration for most implementations.

Integration flow

The Mobile SDK runs on your mobile application, but relies on your backend to create secure tokens. Here’s how it works:

1

Create a client

Register a new client (i.e. customer) using the ComplyCube API.

2

Generate an SDK token

Your backend requests a JWT token tied to that client.

3

Initialize the SDK in your mobile app

Pass the token and settings to the SDK initializer.

4

Capture documents, videos, and selfies

The SDK guides your customer through the required steps.

5

Perform checks

Captured data is securely sent to ComplyCube for verification checks, and results are delivered in real time through the API or webhooks.

Mobile SDK Integration flow

Integration guide

Explore the source code and sample projects on our repository: .

1

Install the SDK

Our SDK requires the repositories below.

repositories {
  mavenCentral(),
  maven { url 'https://maven.fpregistry.io/releases' }
}

dependencies {
    implementation "com.complycube:complycube-sdk:+"
}

2

Create a client

Every verification flow starts with a client (i.e. customer). Use the API to create the client.

This must be done on your mobile app backend server, not the mobile app itself.

Example request

cURL

curl -X POST https://api.complycube.com/v1/clients \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
          "type": "person",
          "email": "[email protected]",
          "personDetails":{
               "firstName": "John",
               "lastName" :"Doe"
          }
        }'

Node.js

Python

PHP

.NET

Example response

The response will contain an id (the Client ID). It is required for the next step.

{
    "id": "5eb04fcd0f3e360008035eb1",
    "type": "person",
    "email": "[email protected]",
    "personDetails": {
        "firstName": "John",
        "lastName": "Doe",
    },
    "createdAt": "2020-01-04T17:24:29.146Z",
    "updatedAt": "2020-01-04T17:24:29.146Z"
}

See Clients API Reference to learn more.

3

Generate an SDK token

Your backend must create an SDK token for each new flow. This token enable customers to send personal data securely from your mobile app to ComplyCube.

Tokens are short-lived and must not be reused.

Example request

cURL

curl -X POST https://api.complycube.com/v1/tokens \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
           "clientId":"CLIENT_ID",
           "appId": "com.complycube.SampleApp"
         }'

Node.js

Python

PHP

.NET

Example response

{
    "token": "<CLIENT_TOKEN>"
}

See SDK Token API Reference to learn more.

4

Prepare the stages

Set up the stages you wish to include in your flow.

Kotlin

val complyCubeBuilder = ComplyCubeSdk.Builder(this, callback =  { }).apply {
    withStages(
        Document(
            identityDocumentType = Passport(), DrivingLicence(),
            useLiveCaptureOnly = false
        ),
        SelfiePhoto()
    )
}

Java

5

Initialize the SDK

You can now initialize a flow. The sequence of stages you specify determines the order in which your client sees those stages.

Kotlin

val complyCubeBuilder = ComplyCubeSdk.Builder(this, callback =  { }).apply {
    withStages(
        Document(
            identityDocumentType = Passport(), DrivingLicence(),
            useLiveCaptureOnly = false
        ),
        SelfiePhoto()
    )
}.start(
    ClientAuth(
        token = "SDK_TOKEN",
        clientId = "CLIENT_ID"
    )
)

Java

6

Perform checks

Using the StageResults returned by the flow, you can trigger your mobile backend to run the necessary checks on your client.

For example, use the result of a selfie and document capture as follows:

• StageResult.Document.Id to run a Document Check.

• StageResult.Document.Id and StageResult.LivePhoto.Id to run an Identity Check.

Example request for a Document Check

cURL

curl -X POST https://api.complycube.com/v1/checks \
     -H 'Authorization: <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{
            "clientId":"CLIENT_ID",
            "type": "document_check",
            "documentId":"DOCUMENT_ID"
         }'

Node.js

Python

PHP

.NET

If you have set up webhooks as described in our webhooks guide, you will be notified once a check completes.

To retrieve the check results, you can perform a get check request.

7

Retrieve verification results

Your mobile backend can retrieve all check results using our API.

All our checks are asynchronous. If you have set up webhooks as described in our webhooks guide, you will be notified once a check completes.

To retrieve the check results, you can perform a get check request.

Example request

cURL

curl -X GET https://api.complycube.com/v1/checks/{:checkId} \
     -H 'Authorization: <YOUR_API_KEY>' 

Node.js

Python

PHP

.NET

Stages

Each stage in the flow can be customized to create the ideal journey for your customers.

The snippet below demonstrates how to set up a customized flow using the ComplyCube Mobile SDK.

Kotlin

var complycubeFlow = ComplyCubeSdk.Builder(this, callback = ...)
  .withSDKToken("SDK_Token")
  .withClientId("CLIENT_ID")
  .withStages(
    Welcome(...),
    Consent(...),
    Document(...),
    SelfiePhoto(...),
    AddressCapture(...),
    ProofOfAddress(...),
    Complete(...)
  )
  .withLookAndFeel(...)
  .withCustomLanguage(...)

complycubeFlow.start()

Java

Welcome

The Welcome screen is always shown first in the verification flow. It displays a welcome message along with a summary of the configured stages the user will complete.

You can customize the screen title to align with your app’s tone and branding.

Kotlin

var welcomeStage = Welcome(
    title = "Custom Screen Title",
    message = "Custom welcome message."
)

Java

Consent

This stage is used to collect explicit user consent before proceeding with the verification flow. It helps you meet regulatory and compliance requirements where applicable.

You can customize the screen title and message to match your legal or branding needs.

Kotlin

var consentStage = Consent(
    title = "Custom Consent Screen Title"
)

Java

Selfie photo and video

You can request either a selfie photo (i.e. a Live Photo) or a selfie video (i.e. a Live Video) from the customer as part of the biometric verification process.

• Photo: Captures a still image and performs a passive liveness check before allowing submission.

• Video: Records a short video where the user completes an on-screen challenge (e.g. head movement or spoken phrase).

If you attempt to add both types of stages, the SDK will throw a ComplyCubeErrorCode.BiometricStageCount error stating multiple conflicting stages.

Kotlin

var selfiePhoto = SelfiePhoto(
    // Enable ML assistance during capture
    isMLAssistantEnabled = false
)

Java

Kotlin

var selfieVideo = SelfieVideo(
    // Enable ML assistance during capture
    isMLAssistantEnabled = false
)

Java

Document

The Document stage allows users to select and capture an identity document for verification (e.g. passport, ID card, residence permit). You can customize these screens to:

• Limit the scope of document types the client can select, e.g., Passport only.

• Set the document issuing countries they are allowed for each document type.

• Add or remove automated capture using smart assistance.

• Show or hide the instruction screens before capture.

• Set a retry limit to allow clients to progress the journey regardless of capture quality.

If you provide only one document type, the document type selection screen will be skipped. The country selection screen will be skipped if you provide only a single country for a given document type.

You can control whether instructional screens are shown before each camera capture by enabling or disabling guidance mode. Only disable guidance if your users are already clearly informed about the capture steps, as these screens help reduce user error and improve capture quality.

Please note the retryLimit you set here will take precedence over the retry limit that has been set globally in your automation settings.

Kotlin

var documentStage = Document(
    // Set document types and limit the enabled countries
    Passport(), DrivingLicence((Country.GB, Country.US)),

    // Enable or disable additional guidance for the user
    isGuidanceEnabled = true,

    // Enable or disable the ability to upload an image from file
    useLiveCaptureOnly = true,

    // Enable ML assistance during capture
    isMLAssistantEnabled = true,
    
    // Set a maximum for quality check attempts before uploadingoft checks
    retryLimit = 3
)

Java

NFC capture

The ComplyCube mobile SDK supports NFC-based RFID chip reading for identity documents equipped with embedded chips. This allows for secure data extraction and high-assurance document authentication.

Please get in touch with your Account Manager or support to get access to our NFC-enabled Mobile SDK.

Pre-requisites

1. Start by adding your access credentials for the ComplyCube NFC-Enabled SDK repository to the gradle.properties file of your mobile app:

artifactory_user= "USERNAME"
artifactory_password= "ENCRYPTED PASS"
artifactory_contextUrl= https://complycuberepo.jfrog.io/artifactory

1. Then, update your project level build.gradle file with the ComplyCube SDK repository Maven settings:

buildscript {
    repositories {
        ...
    }
    dependencies {
        ....
        // Check for the latest version here: 
        // http://plugins.gradle.org/plugin/com.jfrog.artifactory
        classpath "org.jfrog.buildinfo:build-info-extractor-gradle:4+"
    }
    ...
}

allprojects {
    apply plugin: "com.jfrog.artifactory"
    ...
}

artifactory {
  contextUrl = "${artifactory_contextUrl}"  
  resolve {
    repository {
      repoKey = 'cc-gradle-release'
      username = "${artifactory_user}"
      password = "${artifactory_password}"
      maven = true
    }
  }
}

1. Update your module level build.gradle file with the SDK dependency:

dependencies {
    implementation "com.complycube:complycube-sdk:+"
    implementation "com.complycube:nfc-plugin:+"
}

Enabling NFC capture

Kotlin

var documentStage = Document(
    // Add this property to enable NFC
    isNFCEnabled = true,
)

Java

Address capture

This stage allows users to manually enter their residential address. You can customize it to:

• Restrict input to specific countries

• Enable or disable the address autocomplete feature for faster and more accurate entry

Kotlin

var addressCaptureStage = AddressCapture(
    // This enables our address autocomplete
    useAutoComplete = true,
    
    // A list of acceptable countries for address capture feature
    allowedCountries = setOf(Country.GB,Country.US)
)

Java

Proof of address

This stage allows customers to submit a document verifying their residential address. You can configure which document types are accepted, such as utility bills or bank statements, and choose whether customers can upload a file or must capture the document live using their device camera.

By default, this stage includes the address capture stage with autocomplete enabled to assist users during entry. Autocomplete can be disabled if not required.

Kotlin

var poaStage = ProofOfAddress(
    // A list of supported document types that can be submitted
    UtilityBill(), BankStatement(),

    // When disabled, the client will be forced to perform a live capture
    useLiveCaptureOnly = false,

    // This enables address capture during the proof of address flow
    isAddressCaptureEnabled = false
    ...
)

Java

Completion

You can include a completion stage at the end of the flow to confirm that the process has been successfully finished. This screen provides a clear end point for the user and can be customized to display a confirmation message or next steps.

Kotlin

val completionStage = Complete(
    title = "Thank you!",
    message = "Your KYC submission has been completed"
)

Java

Branding

The SDK allows you to customize the UI to match your application’s visual identity. You can define primary and accent colors during configuration to align the verification flow with your brand guidelines. Learn more about our appearance properties (see below).

Kotlin

complycubeFlow.withLookAndFeel(
    lookAndFeel = LookAndFeel(
        primaryButtonBgColor = Color.RED,
        /* Can also be set to UIInterfaceStyle.LIGHT 
        or UIInterfaceStyle.INHERITED */
        uiInterfaceStyle = UIInterfaceStyle.DARK
    )
)

Java

Appearance properties

Appearance Property	Description
primaryButtonBgColor	Primary action button background color.
primaryButtonTextColor	Primary action button text color.
primaryButtonBorderColor	Primary action button border color.
secondaryButtonBgColor	Secondary button background color.
secondaryButtonPressedBgColor	Secondary action button pressed background color.
secondaryButtonTextColor	Secondary action button text color.
secondaryButtonBorderColor	Secondary action button border color.
documentTypeSelectorBgColor	Document type selection button color.
documentTypeSelectorBorderColor	Document type selection button border color.
documentTypeSelectorTitleTextColor	Document type selection title text color.
documentTypeSelectorDescriptionTextColor	Document type selection description text color.
documentTypeSelectorIconColor	Document type selection icon color.
bodyTextColor	Screen body text color.
linkButtonTextColor	Links color.
headingTextColor	Title heading text color.
subheadingTextColor	Subheading text color.
infoPanelTitleColor	Information panel title color.
infoPanelDescriptionTextColor	Information panel description text color.
infoPanelBgColor	Information panel background color.
infoPanelIconColor	Information panel icon color.
errorPanelTitleColor	Error panel title color.
errorPanelDescriptionTextColor	Error panel description text color.
errorPanelBgColor	Error panel background color.
errorPanelIconColor	Error panel icon color.
cameraButtonBgColor	Camera capture button background color.
uiInterfaceStyle	Set the SDK to use dark mode, light mode, or system Inherited.

Localization

The SDK supports the languages listed below.

• Arabic - ar 🇦🇪

• Chinese (Simplified) - zh 🇨🇳

• Chinese (Traditional) - hk 🇨🇳

• Dutch - nl 🇳🇱

• English - en 🇺🇸

• French - fr 🇫🇷

• German - de 🇩🇪

• Hindi - hi 🇮🇳

• Indonesian - id 🇮🇩

• Italian - it 🇮🇹

• Japanese - ja 🇯🇵

• Korean - ko 🇰🇷

• Norwegian - no 🇳🇴

• Polish - po 🇵🇱

• Portuguese - pt 🇵🇹

• Spanish - es 🇪🇸

• Swedish - sv 🇸🇪

• Thai - th 🇹🇭

• Vietnamese - vi 🇻🇳

Result handling

To manage the outcome of a verification session, you must implement the success, cancelled, and error callbacks.

On a successful completion (onSuccess), you can trigger check requests from your backend using the resource IDs returned in the result object. These IDs correspond to the uploaded assets (e.g. documents, selfies) and can be used to initiate verification checks via the ComplyCube API.

If the user exits the flow before completion, the onCancelled callback is invoked with a descriptive reason indicating why the session was cancelled (e.g. user exit, timeout, permission denied)

In some cases, the customer may cancel the flow after completing one or more capture stages. If this occurs, any data captured prior to cancellation, such as documents or biometric media, may have already been uploaded to their client record.

If the SDK encounters an issue, the onError callback is triggered with a ComplyCubeError object containing the error type and message. Refer to the error codes (see below), for a full list of possible error cases.

Kotlin

//Register a result handler to process the outcome of the flow.
var complycubeFlow =
    ComplyCubeSdk.Builder(
        this,
        callback = { result ->
            when (result) {
                is Result.Success -> { 
                /*
                Handling successful results:
                Our default flow includes three components: an Identity Document,
                a Selfie (Live Photo), and a Proof of Address. Upon successful 
                completion, the 'Result' will contain an array of stage results.
                Each stage result provides the ID of the uploaded item:
                  - 'StageResult.Document.Id': the uploaded Document ID.
                  - 'StageResult.LivePhoto.Id': the uploaded Live Photo ID.
                  - 'StageResult.ProofOfAddress.Id': the uploaded PA Document ID.
                */
                }
                is Result.Cancelled -> { /* Handle Cancelled result */ }
                is Result.Error -> {
                    // Handle errors
                    when (result.errorCode) {
                        ComplyCubeErrorCode.UploadError -> {
                            // Handle Upload error
                        }
                        ComplyCubeErrorCode.BiometricStageCount -> {
                            // Handle BiometricStageCount error
                        }
                        // ...other error handlers
                    }
                }
                else -> {}
            }
        }
    )

complycubeFlow.start(clientAuth)

Java

Error codes

Error Type	Description
BiometricStageCount	The configuration includes duplicate selfie photo or selfie video stages.
Cancelled	The client cancelled the flow and exited the SDK (triggered the onCancelled callback).
Connectivity	A network error has occurred.
DocumentMandatory	A document stage is required based on the configured stages but has not been included.
ExpiredToken	The SDK token has expired. Generate a new token and restart the flow.
FlowError	An unrecoverable error occurred during the flow.
InvalidCountryCode	An invalid country code was provided.
JailBroken	The SDK cannot run on this device because it has been jailbroken or compromised.
NoDiskAccess	The client denied disk access permissions required by the SDK.
NoDocumentTypes	A document stage was initialized without specifying any document types.
NoResult	No result was returned to the callback. If this persists, please contact support.
NoUserConsent	The client has not provided consent to proceed with the SDK flow.
NotAuthorized	The SDK attempted to access an endpoint it is not authorized to use.
Unknown	An unexpected error occurred. If this happens repeatedly, contact support.
UnsupportedCountryTypeCombination	The selected country and document type combination is not supported.
UnsupportedDocumentType	The provided document type is not supported.
UploadError	An error occurred while uploading a document or selfie.
UploadRequireGuidance	If useLiveCaptureOnly is set to false, guidance must be enabled by setting isGuidanceEnabled to true.

Events tracking

The SDK tracks a range of events throughout the verification flow, covering all key user interactions across stages. See below for the list of events.

If you need to implement custom analytics, you can hook into these events and trigger your own tracking logic accordingly.

To incorporate your own tracking, define a function and apply it using withEventHandler when initializing the Builder:

Kotlin

complycubeBuilder.withEventHandler(true) { event ->
    // Insert custom user tracking here
}

Java

Events

Event
INTRO The client reached the intro screen.
CONSENT_STAGE The client reached the consent screen.
CONSENT_STAGE_WARNING The client attempted to exit without giving consent.
CAMERA_ACCESS_PERMISSION The client reached the camera permission request screen.
DOCUMENT_STAGE_CAPTURE_GUIDANCE The client reached the document capture guidance screen.
DOCUMENT_STAGE_DOCUMENT_TYPE The client has reached the document type selection screen for a document capture.
DOCUMENT_STAGE_SELECT_COUNTRY The client reached the country selection screen for a document capture.
DOCUMENT_STAGE_ONE_SIDE_CAMERA The client reached the capture camera stage for a one-sided ID document.
DOCUMENT_STAGE_ONE_SIDE_CAMERA_MANUAL_MODE The client reached the manual camera capture screen of a one-sided ID document.
DOCUMENT_STAGE_ONE_SIDE_CHECK_QUALITY The client reached the quality preview screen for a one-sided ID document.
DOCUMENT_STAGE_TWO_SIDE_CAMERA_FRONT The client reached the camera capture screen for the front side of a two-sided ID document.
DOCUMENT_STAGE_TWO_SIDE_CAMERA_FRONT_MANUAL_MODE The client reached the manual camera capture screen for the front side of a two-sided ID document.
DOCUMENT_STAGE_TWO_SIDE_CHECK_QUALITY_FRONT The client reached the quality preview screen for the front side of a two-sided ID document.
DOCUMENT_STAGE_TWO_SIDE_CAMERA_BACK The client reached the camera capture screen for the back side of a two-sided ID document.
DOCUMENT_STAGE_TWO_SIDE_CAMERA_BACK_MANUAL_MODE The client reached the manual camera capture screen for the back side of a two-sided ID document.
DOCUMENT_STAGE_TWO_SIDE_CHECK_QUALITY_BACK The client reached the quality preview screen for the back side of a two-sided ID document.
BIOMETRICS_STAGE_SELFIE_CAPTURE_GUIDANCE The client reached the selfie capture guidance screen.
BIOMETRICS_STAGE_SELFIE_CAMERA The client reached the selfie photo capture camera screen.
BIOMETRICS_STAGE_SELFIE_CAMERA_MANUAL_MODE The client reached the manual selfie photo capture camera screen.
BIOMETRICS_STAGE_SELFIE_CHECK_QUALITY The client reached the selfie capture photo review screen.
BIOMETRICS_STAGE_VIDEO_CAMERA The client reached the video selfie camera screen.
BIOMETRICS_STAGE_VIDEO_CAMERA_MANUAL_MODE The client reached the manual capture camera screen for a video selfie.
BIOMETRICS_STAGE_VIDEO_ACTION_ONE The client reached the first action in a video selfie capture.
BIOMETRICS_STAGE_VIDEO_ACTION_TWO The client reached the second action in a video selfie capture.
BIOMETRICS_STAGE_VIDEO_CHECK_QUALITY The client reached the manual selfie video capture camera screen.
PROOF_OF_ADDRESS_STAGE_CAPTURE_GUIDANCE The client reached the proof of address capture guidance screen.
PROOF_OF_ADDRESS_STAGE_DOCUMENT_TYPE The client reached the document type selection screen for a proof of address capture.
PROOF_OF_ADDRESS_STAGE_SELECT_COUNTRY The client reached the country selection screen for a proof of address capture.
PROOF_OF_ADDRESS_STAGE_ONE_SIDE_CAMERA The client reached the capture camera stage for a one-sided proof of address document.
PROOF_OF_ADDRESS_STAGE_ONE_SIDE_CAMERA_MANUAL_MODE The client reached the manual capture camera stage for a one-sided proof of address document.
PROOF_OF_ADDRESS_STAGE_ONE_SIDE_CHECK_QUALITY The client has reached the quality preview screen for a one-sided proof of address document.
PROOF_OF_ADDRESS_STAGE_TWO_SIDE_CAMERA_FRONT The client reached the capture camera stage for the front side of a two-sided proof of address document.
PROOF_OF_ADDRESS_STAGE_TWO_SIDE_CAMERA_FRONT_MANUAL_MODE The client reached the manual capture camera stage for the front side of a two-sided proof of address document.
PROOF_OF_ADDRESS_STAGE_TWO_SIDE_CHECK_QUALITY_FRONT The client reached the quality preview screen for the front side of a two-sided proof of address document.
PROOF_OF_ADDRESS_STAGE_TWO_SIDE_CAMERA_BACK The client reached the capture camera stage for the back side of a two-sided proof of address document.
PROOF_OF_ADDRESS_STAGE_TWO_SIDE_CAMERA_BACK_MANUAL_MODE The client reached the manual capture camera stage for the back side of a two-sided proof of address document.
PROOF_OF_ADDRESS_STAGE_TWO_SIDE_CHECK_QUALITY_BACK The client reached the quality preview screen for the back side of a two-sided proof of address document.
COMPLETION_STAGE The client has reached the completion screen.

Token expiry handling

To handle token expiration gracefully, you can provide a callback function that generates a new SDK token when needed. This allows the flow to continue seamlessly without requiring the user to restart the session manually.

Kotlin

var complyCubeBuilder = ComplyCubeSdk.Builder(this,
    callback = { result ->
        if (result is Result.Error) {
            if (result.errorCode is ComplyCubeErrorCode.ExpiredToken) {
                // Insert custom token renewal code here
            }
        }
    }
)

Java