iOS Guide

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.

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

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.

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

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.

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 is triggered when the DocV SDK encounters an error or when the consumer exits the flow without completing it. It returns a message printed with the deviceSessionToken and specific error details.

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

Possible `onError` messages

The following error messages may be returned by the Socure DocV SDK:

No internet connection
Failed to initiate the session
Permissions to open the camera declined by the user
Consent declined by the user
Failed to upload the documents
Invalid transaction token
Invalid or missing SDK key
Session expired
Scan canceled by the user
Unknown error

Step 7: Receive the verification results

After the consumer finishes the document capture and upload process with the Caprture 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"
}

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

launchSocureDocV Parameters

Step 6: Handle the response

Session callbacks

onSuccess response

onError response

Possible onError messages

Step 7: Receive the verification results

Use the CocoaPods-generated `.xcworkspace` file

`launchSocureDocV` Parameters

`onSuccess` response

`onError` response

Possible `onError` messages