## Before you start  
Make sure you have the following:

Get a valid API key from the [Developer Workbench > API Keys](https://riskos.socure.com/developers/api-keys) page in RiskOS™.

Get a valid SDK key from the [Developer Workbench > SDK Keys](https://help.socure.com/riskos/docs/integration-guide-authentication#/) page in RiskOS™.

(Optional) Add your IP address to the [allowlist](https://help.socure.com/riskos/docs/ip-filtering#/) 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:

```undefined
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.

**Kotlin**  
```kotlin
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:

```undefined
<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:

```undefined
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:

| Parameter | Required | Description |
| --- | --- | --- |
| `language` | Optional | Determines the [language package](https://help.socure.com/riskos/docs/language-options) for the UI text on the Capture App.<br>**Note**: Socure can quickly add support for any new language requirement that is not listed above. For more information, contact [support@socure.com](mailto:support@socure.com). |
| `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™](https://help.socure.com/riskos/docs/capture-app#/).<br>- If this field is empty, the Capture App will use the flow marked as **Default** in RiskOS™.<br>- 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.

2. 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.

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

**JSX**  
```jsx
import { launchSocureDocVWithPromise } from '@socure-inc/docv-react-native';
```

2. Call `launchSocureDocVWithPromise` inside an `async` function:

**JSX**  
```jsx
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.

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

**JSX**  
```jsx
import { launchSocureDocV } from '@socure-inc/docv-react-native';
```

2. Call `launchSocureDocV` to initiate the Socure DocV SDK:

**JSX**  
```jsx
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.

**JavaScript**  
```javascript
{
  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`.

**JavaScript**  
```javascript
{
  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.

**JSON**  
```json
{
  "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 2 days ago