DocV React Native iOS

Learn how to integrate the Predictive Document Verification (DocV) into a React Native iOS 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 following requirements: Xcode version 14.1+ and support for iOS 13 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

In your root project folder, open your Podfile with a text editor.
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:

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

Go to the ios folder in your project:

cd ios

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:

Close Xcode if it's already open.
Use the .xcworkspace file reopen your project in Xcode.
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

Return to your root project folder in the command line.
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

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

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

{
  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_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.

{
  "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 iOS app

Add project dependencies

Install the dependencies

Use the CocoaPods-generated .xcworkspace file

Request camera 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 the response

Session callbacks

onSuccess response

onError response

Error reference

Step 7: Receive the verification results

Use the CocoaPods-generated `.xcworkspace` file

`launchSocureDocV` parameters

`onSuccess` response

`onError` response