## 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 following requirements: Xcode version 15.3+ and support for iOS 15 and later.

Set up the React Native CLI. See the [React Native documentation](https://reactnative.dev/docs/environment-setup) for instructions.

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.

> 📘  
> **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 iOS app

For the iOS app, you can install the DocV iOS SDK into your project using Cocoapods. If you do not already have the CocoaPods tool installed, see the CocoaPods Getting Started guide.

#### Add project dependencies

1. In your root project folder, open your `Podfile` with a text editor.
2. Specify the following project dependencies:
   - Replace the deployment target with `platform :ios, '13.0'`.
   - Add the following line:

```undefined
pod 'socure-docv-react-native', :path => '../node_modules/@socure-inc/docv-react-native'
```

Once completed, your `Podfile` should look like the following example:

Swift

```swift
require_relative '../node_modules/react-native/scripts/react_native_pods'
require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'

platform :ios, '13.0'
install! 'cocoapods', :deterministic_uuids => false

production = ENV["PRODUCTION"] == "1"

target 'SocureDocVDemo' do
  config = use_native_modules!

# Flags change depending on the env values.
  flags = get_default_flags()

use_react_native!(
    :path => config[:reactNativePath],
    # to enable hermes on iOS, change `false` to `true` and then install pods
    :production => production,
    :hermes_enabled => flags[:hermes_enabled],
    :fabric_enabled => flags[:fabric_enabled],
    :flipper_configuration => FlipperConfiguration.enabled,
    # An absolute path to your application root.
    :app_path => "#{Pod::Config.instance.installation_root}/.."
  )

target 'SocureDocVDemoTests' do
    inherit! :complete
    # Pods for testing
  end

post_install do |installer|
    react_native_post_install(installer)
    __apply_Xcode_12_5_M1_post_install_workaround(installer)
  end

pod 'socure-docv-react-native', :path => '../node_modules/@socure-inc/docv-react-native'

end
```

#### Install the dependencies

1. Go to the `ios` folder in your project:

```undefined
cd ios
```

2. Install the Cocoapods dependencies by running the following command:

```undefined
pod install
```

#### Use the CocoaPods-generated `.xcworkspace` file

The `pod install` command generates a `.xcworkspace` file with all the configured dependencies. To continue with the installation, complete the following:

1. Close Xcode if it's already open.
2. Use the `.xcworkspace` file to reopen your project in Xcode.
3. Check that your deployment target is set to iOS 13.0 or later.

#### Request camera permissions

The DocV iOS SDK requires a device's camera permission to capture identity documents. Upon the first invocation of the SDK, the app will request camera permission from the consumer. If the app does not already use the camera, you must add the following to the app’s `Info.plist file`:

| Key | Type | Value |
| --- | --- | --- |
| Privacy - Camera Usage Description | String | "This application requires use of your camera in order to capture your identity documents." |

> 📘  
> **Note**:  
> We recommend checking for camera permission before calling the DocV SDK launch API.

### Step 3: Run the app

1. Return to your root project folder in the command line.
2. Use the following command to run the app:

```undefined
react-native run-ios
```

### 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 iOS 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 the response

You can use either callbacks or webhooks to track the consumer's progress in the document capture and upload process, and receive error messages if the flow fails.

#### Session 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_VIEW_CONTROLLER` | Failed to get root view controller | iOS only — the root `UIViewController` could not be resolved. |
| `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"
}
```