DocV React Native iOS

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

Set up the React Native CLI. See the React Native documentation 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:

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:

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

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

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:

cd ios

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

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:

📘
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:

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:

📘
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

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

2. Call launchSocureDocVWithPromise inside an async function:

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

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

2. Call launchSocureDocV to initiate the Socure DocV SDK:

JSX

launchSocureDocV(
  'docVTransactionToken',
  'SOCURE_SDK_KEY',
  userSocureGov,
  onSuccess,
  onError
);

launchSocureDocV parameters

The following table lists the parameters for the launchSocureDocV function:

📘
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

{
  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

{
  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:

📘
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

{
  "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"
}