DocV React Native Android

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 23 / OS version 6.0 or later).

Verify your project uses React Native 0.79.0 or later and React 19.0.0 or later, as required by the @socure-inc/docv-react-native wrapper.

The DocV SDK is compiled with the following:

compileSdkVersion: 36
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.

📘
React Native New Architecture:
Starting with version 5.2.8, the DocV React Native wrapper fully supports the React Native New Architecture (TurboModules and Fabric) introduced in React Native 0.79. The wrapper supports both the Old and New Architecture from the same package, with no configuration changes required.

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 setting the minSdkVersion to at least 23 and the compileSdkVersion to at least 36.

buildscript {
              .....
            ext {
                 ....
                minSdkVersion = 23
                compileSdkVersion = 36
                .....
            }
}

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

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

Parameter	Required	Description
`language`	Optional	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_key`	Optional	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.

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

The wrapper exposes two APIs. Use launchSocureDocVWithPromise for new integrations and any app running React Native 0.79 or later. Use launchSocureDocV if your codebase already uses callbacks or you need to support older React Native versions.

Option A: Promise-based API (recommended)

The Promise-based API is the recommended approach for New Architecture apps. It uses async/await and standard JavaScript error handling.

Add the following code to your App.js file to import launchSocureDocVWithPromise:

import { launchSocureDocVWithPromise } from '@socure-inc/docv-react-native';

Call launchSocureDocVWithPromise inside an async function:

try {
  const result = await launchSocureDocVWithPromise(
    'docVTransactionToken',
    'SOCURE_SDK_KEY',
    false // useSocureGov
  );
  console.log('Success:', result.deviceSessionToken);
} catch (error) {
  console.log('Error code:', error.code);
  console.log('Error message:', error.message);
}

Returns: A Promise<DocVResult> that resolves with { deviceSessionToken: string } on success, or rejects with an error object containing code and message on failure. See the error reference in Step 6 for all error codes.

Option B: Callback-based API (legacy)

The callback-based API remains available for backward compatibility. Existing integrations do not require any code changes.

Add the following code to your App.js file to import launchSocureDocV:

import { launchSocureDocV } from '@socure-inc/docv-react-native';

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:

Parameter	Type	Description
`SOCURE_SDK_KEY`	String	The unique SDK key obtained from RiskOS™ used to authenticate the SDK.
`docVTransactionToken`	String	The transaction token retrieved from the API response of the `/api/evaluation` endpoint. Required to initiate the document verification session.
`useSocureGov`	Bool	A Boolean flag indicating whether to use the GovCloud environment. It defaults to `false`. This is only applicable for customers provisioned in the SocureGov environment.
`onSuccess`	Function	A callback function invoked when the flow completes successfully.
`onError`	Function	A callback function invoked when the flow fails.

📘
New Architecture:
Under the React Native New Architecture, launchSocureDocV automatically routes through the TurboModule promise API and bridges the result back to your onSuccess and onError callbacks. No code changes are required.

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 triggers when the DocV SDK encounters an error or when the consumer exits the flow without completing it. It returns an object containing a machine-readable code, a human-readable error message, and the deviceSessionToken.

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

Error reference

The onError callback (and the Promise rejection) returns the following error codes and messages:

`code`	`error` message	Description
`ERR_NO_INTERNET`	No internet connection	The device has no network connectivity.
`ERR_SESSION_INITIATION`	Failed to initiate the session	The SDK couldn't start a verification session with Socure servers.
`ERR_CAMERA_PERMISSION`	Permissions to open the camera declined by the user	The user denied camera access.
`ERR_CONSENT_DECLINED`	Consent declined by the user	The user declined the consent screen.
`ERR_UPLOAD_FAILURE`	Failed to upload the documents	The captured images could not be uploaded.
`ERR_INVALID_TOKEN`	Invalid transaction token	The `docVTransactionToken` is missing, malformed, or already used.
`ERR_INVALID_KEY`	Invalid or missing SDK key	The SDK key is invalid or was not provided.
`ERR_SESSION_EXPIRED`	Session expired	The verification session timed out before completion.
`ERR_USER_CANCELED`	Scan canceled by the user	The user dismissed the capture flow before completing it.
`ERR_NO_ACTIVITY`	App activity is null	Android only — the host Activity was not available when the SDK attempted to launch.
`ERR_NO_DATA`	No result data returned from SDK	Android only — the SDK activity returned without data.
`ERR_ALREADY_IN_PROGRESS`	A DocV session is already in progress	A previous call has not yet resolved. Wait for it to complete before launching again.
`ERR_UNKNOWN`	Unknown error	An unrecognized error occurred.

📘
Migration note:
The error field (the human-readable message) is preserved from previous versions. The new code field (a machine-readable constant) was added in version 5.2.8 to enable reliable programmatic error handling without string matching.

Step 7: Receive the verification results

After the consumer finishes the document capture and upload process with the Capture 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 1 day ago

Did this page help you?

Before you start

Step 1: Install the React Native wrapper

Step 2: Configure your Android app

Camera permissions

Required permissions

Step 3: Run the app

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

Call the Evaluation endpoint

Step 5: Import and launch the SDK

Option A: Promise-based API (recommended)

Option B: Callback-based API (legacy)

launchSocureDocV parameters

Step 6: Handle response callbacks

onSuccess response

onError response

Error reference

Step 7: Receive the verification results

`launchSocureDocV` parameters

`onSuccess` response

`onError` response