User Guides
Home
Start typing to search…

Android Guide

Learn how to integrate the Predictive Document Verification (DocV) into a React Native Android app, including setup, configuration, and handling verification results.

Before you start

Make sure you have the following:

Get a valid API key from the Developer Workbench > API Keys page in RiskOS™.
Get a valid SDK key from the Developer Workbench > SDK Keys page in RiskOS™.
(Optional) Add your IP address to the allowlist in RiskOS™.
Verify your development environment meets the minimum requirements (Android SDK version 22 / OS version 5.1 or later).

The DocV SDK is compiled with the following:

  • compileSdkVersion: 34
  • Java: 17
📘

Note:

Document and Selfie Auto Capture features require Android SDK Version 28 (OS Version 9.0) and later with at least 3 GB of RAM. If the device does not meet these requirements, only the manual capture feature will be available.


Step 1: Install the React Native wrapper

In your React Native project, install the DocV React Native wrapper by running the following NPM command:

npm install @socure-inc/docv-react-native

Step 2: Configure your Android app

For the Android app, add your project dependencies by going to the module level build.gradle file and making sure the minSdkVersion is set to at least 22 and the compileSdkVersion is set to at least 32.

buildscript {
              .....
            ext {
                 ....
                minSdkVersion = 22
                compileSdkVersion = 33
                .....
            }
}

Camera permissions

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

📘

Note:

We recommend you check for camera permissions before calling the Socure DocV SDK's launch API.


Required permissions

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"/>

Step 3: Run the app

From the command line, go to your root project folder and enter the following command to run the app:

react-native run-android

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

To initiate the verification process, generate a transaction token (docvTransactionToken) by calling the Evaluation endpoint. We strongly recommend that customers generate this token via a server-to-server API call and then pass it to the DocV SDK to ensure the security of their API key and any data they send to Socure.


Call the Evaluation endpoint

  1. From your backend, make a POST request to the /api/evaluation endpoint specifying the following information in the config object:
ParameterRequiredDescription
languageOptional

Determines the language package for the UI text on the Capture App.

Note: Socure can quickly add support for any new language requirement that is not listed above. For more information, contact [email protected].

use_case_keyOptional

Deploys a customized Capture App flow on a per-transaction basis. Replace the customer_use_case_key value with the name of the flow you created in RiskOS™.

  • If this field is empty, the Capture App will use the flow marked as Default in RiskOS™.
  • If the value provided is incorrect, the SDK will return an Invalid Request error.
📘

Note:

We recommend including as much consumer PII in the body of the request as possible to return the most accurate results.

  1. When you receive the API response, collect the docvTransactionToken. This value is required to initialize the DocV Android SDK.

Step 5: Import and launch the SDK

  1. Add the following code to your App.js file to import launchSocureDocV:
import { launchSocureDocV } from '@socure-inc/docv-react-native';
  1. Call launchSocureDocV to initiate the Socure DocV SDK:
launchSocureDocV(
  'docVTransactionToken',
  'SOCURE_SDK_KEY',
  userSocureGov,
  onSuccess,
  onError
);

launchSocureDocV Parameters

The following table lists the parameters for the launchSocureDocV function:

ParameterTypeDescription
SOCURE_SDK_KEYStringThe unique SDK key obtained from RiskOS™ used to authenticate the SDK.
docVTransactionTokenStringThe transaction token retrieved from the API response of the /api/evaluation endpoint. Required to initiate the document verification session.
useSocureGovBoolA Boolean flag indicating whether to use the GovCloud environment. It defaults to false. This is only applicable for customers provisioned in the SocureGov environment.
onSuccessFunctionA callback function invoked when the flow completes successfully.
onErrorFunctionA callback function invoked when the flow fails.

Step 6: Handle response callbacks

Your app can receive response callbacks from the launchSocureDocV function when the flow either completes successfully or returns with an error. The SDK represents these outcomes using the onSuccess and onError callback functions.


onSuccess response

The onSuccess callback is triggered when the consumer successfully completes the verification flow and the captured images are uploaded to Socure's servers. It returns an object containing a device session token, which can be used for accessing device details about the specific session.

{
  deviceSessionToken: 'eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzd3QiOiJmZWJlMDYxNS0wYjgxLTRkNTMtYjgyMS03YTAxNjUwZTFiMjEifQ.kz3W8oQxmlqWk1x3W4mf7BSgGmr-qAyvN6fxR_yusbfWdznYVAzdeabHdyW0vAFGgGYvEmyX-5YUtHDMQB0ptA';
}

onError response

The onError callback is triggered when the DocV SDK encounters an error or when the consumer exits the flow without completing it. It returns a message printed with the deviceSessionToken and specific error details.

{
  deviceSessionToken: 'eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzd3QiOiJmZWJlMDYxNS0wYjgxLTRkNTMtYjgyMS03YTAxNjUwZTFiMjEifQ.kz3W8oQxmlqWk1x3W4mf7BSgGmr-qAyvN6fxR_yusbfWdznYVAzdeabHdyW0vAFGgGYvEmyX-5YUtHDMQB0ptA',
  error: 'Scan canceled by the user'
}

Possible onError messages

The following error messages may be returned by the Socure DocV SDK:

  • No internet connection
  • Failed to initiate the session
  • Permissions to open the camera declined by the user
  • Consent declined by the user
  • Failed to upload the documents
  • Invalid transaction token
  • Invalid or missing SDK key
  • Session expired
  • Scan canceled by the user
  • Unknown error

Step 7: Receive the verification results

After the consumer finishes the document capture and upload process with the Caprture App, RiskOS™ runs the evaluation process and returns the results in the evaluation_completed webhook event. The DocV verification results are included in the data_enrichments array within the payload.

Alternatively, you can fetch the RiskOS™ results by making a GET request to the /api/evaluation endpoint.

{
  "data": {
    "decision": "REVIEW",
    "decision_at": "2025-04-08T18:27:31.924196163Z",
    "environment_name": "",
    "eval_at": "2025-04-08T18:27:31.924196043Z",
    "eval_id": "8770e076-f568-48a9-8201-dca13087e592",
    "eval_source": "API",
    "evaluation_status": "evaluation_completed",
    "id": "abc-test-123",
    "notes": "Test Notes",
    "reason_codes": ["test"],
    "review_queues": ["Default Queue"],
    "status": "OPEN",
    "sub_status": "Surveillance",
    "tags": ["test"],
    "data_enrichments": [
      {
        "third_party_name": "Socure Document Request",
        "third_party_endpoint": "https://service.socure.com/api/5.0/documents/request",
        "third_party_provider": "SocureDocRequest",
        "status_code": 200,
        "request": {
          "country": "US",
          "firstName": "John",
          "surName": "Smith"
        },
        "response": {
          "data": {
            "docvTransactionToken": "9979eda7-9694-476d-ab8b-e6bbc0153dc3",
            "eventId": "9979eda7-9694-476d-ab8b-e6bbc0153dc3",
            "qrCode": "data:image/png;base64,iVBO......K5CYII=",
            "url": "https://verify.socure.com/#/dv/9979eda7-9694-476d-ab8b-e6bbc0153dc3"
          },
          "referenceId": "b902702f-a07a-4180-acdd-20266f776ba3"
        },
        "is_source_cache": false,
        "total_attempts": 1
      },
      {
        "third_party_name": "Socure Predictive Document Verification Prod",
        "third_party_endpoint": "https://service.socure.com/api/3.0/EmailAuthScore",
        "third_party_provider": "Socure",
        "status_code": 200,
        "request": {
          "country": "US",
          "docvTransactionToken": "9979eda7-9694-476d-ab8b-e6bbc0153dc3",
          "firstName": "John",
          "modules": ["documentverification"],
          "parentTxnId": "e3c35948-5141-4e3d-836d-31ee7fcc8b8d",
          "surName": "Smith",
          "workflow": "api_consumer_onboarding"
        },
        "response": {
          "documentVerification": {
            "decision": {
              "name": "standard",
              "value": "accept"
            },
            "documentType": {
              "country": "USA",
              "state": "WA",
              "type": "Drivers License"
            },
            "reasonCodes": [
              "I834",
              "I845",
              "I831",
              "I820",
              "I836",
              "I838",
              "R823",
              "R822"
            ]
          },
          "referenceId": "06bf2f66-7d18-47c2-b12f-4be3a30e1d49"
        },
        "is_source_cache": false,
        "total_attempts": 1
      },
      {
        "third_party_name": "Socure Image Request Prod",
        "third_party_endpoint": "https://upload.socure.com/api/5.0/documents/{referenceId}",
        "third_party_provider": "SocureImageRequest",
        "status_code": 200,
        "request": {
          "referenceId": "06bf2f66-7d18-47c2-b12f-4be3a30e1d49"
        },
        "response": {
          "docId": "077bd0be-129e-4352-bb6b-cc07c9a86fdc"
        },
        "is_source_cache": false,
        "total_attempts": 1
      }
    ],
    "workflow": "api_consumer_onboarding",
    "workflow_id": "7ba6948f-502d-446e-a1e5-45d66cc50983",
    "workflow_version": "1.0.0"
  },
  "event_at": "2025-04-08T18:27:31.9244894Z",
  "event_id": "df9252b5-85c8-426e-9590-8f51b6e5b5c0",
  "event_type": "evaluation_completed"
}

Updated about 1 month ago