Socure Android SDK v5 Integration Guide

Getting started

• Get a SDK key from GD to initialize and authenticate the DocV Android SDK
• Check that your development environment meets the following requirements:
  • Android SDK Version 22 (OS Version 5.1) and later
• The DocV SDK is compiled with the following:
  • compileSdkVersion: 34
  • Java: 17

GitHub Android Library for Socure's Document Verification Product

Step 1: Generate a transaction token and configure the Capture App

To initiate the verification process, generate a transaction token (docvTransactionToken) by calling the Document Request endpoint v5.

Call the IDV Socure capture RUL endpoint

POST /programs/{programCode}/accounts/{accountIdentifier}/socureDocumentRequest

Step 2: Add the DocV Android SDK

To add the DocV SDK to your application, include the Socure DocV SDK Maven repository in your build.gradle file at the end of the allprojects > repositories section:

allprojects {
    repositories {
        ...
        maven { url 'https://sdk.socure.com' }
    }
}

In your module level build.gradle file, add the following Socure DocV SDK dependency and replace x.y.z with the DocV Android SDK version number (for example: 5.0.7):

dependencies {
    implementation 'com.socure.android:docv-capture:5.0.7'
}

Camera and file permissions

The DocV SDK requires camera and file permission to capture identity documents. Upon the first invocation of the SDK, your app will request camera and file permission from the user.

Note: We recommend you check for camera and file permissions before calling the Socure DocV SDK’s launch API.

Ensure that your app manifest has been set up properly to request the following required permissions:

<uses-feature android:name="android.hardware.camera" />

<!-- Declare permissions -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Initialize and launch the SDK

To enable the DocV SDK functionality, add the following code to your app:

class Activity : AppCompatActivity() {

    private lateinit var startForResult: ActivityResultLauncher<Intent>

    override fun onCreate(savedInstanceState: Bundle?) {
        ...

        startForResult = registerForActivityResult(
            ActivityResultContracts.StartActivityForResult()
        ) { result: ActivityResult ->
            result.data?.let { data ->
                SocureSdk.getResult(data) { sdkResult ->
                    Log.d(TAG, "onResult called: $sdkResult")

                    if (sdkResult is SocureDocVSuccess) {
                        Log.d(
                            TAG,
                            "success: ${sdkResult.deviceSessionToken}"
                        )
                    } else {
                        val error = sdkResult as? SocureDocVFailure
                        Log.d(
                            TAG,
                            "error: ${error?.deviceSessionToken}, " +
                            "${error?.error}"
                        )
                    }
                }
            }
        }

        // Launch the SDK using the intent
        startForResult.launch(
            SocureSdk.getIntent(
                context,
                SocureDocVContext(
                    docvTransactionToken,
                    SDKKey,
                    useSocureGov
                )
            )
        )
    }
}

startForResult.launch function parameters

The following table lists the arguments passed to the startForResult.launch function through SocureSdk.getIntent:

Handle the response

Your app can receive response callbacks from the startForResult function when the flow either completes successfully or returns with an error. The SDK represents these outcomes with the SocureDocVSuccess and SocureDocVFailure classes.

Success

If the consumer successfully completes the verification flow and the captured images are uploaded to Socure's servers, the SDK returns a SocureDocVSuccess result. This result contains a deviceSessionToken, a unique identifier for the session that can be used for accessing device details about the specific session.

if (result is SocureDocVSuccess) {
    Log.d(TAG, "success: ${result.deviceSessionToken}")
}

Failure

If the consumer exits the flow without completing it or an error occurs, the SDK returns a SocureDocVFailure result. This result contains both the deviceSessionToken and SocureDocVError, which provides specific details about the reason for failure.

val error = result as? SocureDocVFailure
Log.d(TAG, "error: ${error?.deviceSessionToken}, ${error?.error}")

When the SDK returns a failure, it provides a SocureDocVError enum with specific error cases relevant to the Capture App flow:

enum class SocureDocVError {
    SESSION_INITIATION_FAILURE,
    SESSION_EXPIRED,
    INVALID_PUBLIC_KEY,
    INVALID_DOCV_TRANSACTION_TOKEN,
    DOCUMENT_UPLOAD_FAILURE,
    CONSENT_DECLINED,
    CAMERA_PERMISSION_DECLINED,
    USER_CANCELED, 
    NO_INTERNET_CONNECTION, 
    UNKNOWN
}

The following table lists the error values that can be returned by the SocureDocVError enum:

Step 3: Fetch the verification results

When the consumer successfully completes the document capture and upload process, call the Partner API to verify the IDV result.

POST /programs/{programCode}/accounts/{accountIdentifier}/users/{userIdentifier}/kycGates/idvsocure

Refer to IDV Socure request