React Native Module

Latest release: Version 1.31.3 (Changelog)


yarn add @sumsub/react-native-mobilesdk-module




Use Kotlin 1.5 and API level 21 (Android 5.0) or higher in your Android project.

Add the following repository to your android/build.gradle file.

allprojects {
  repositories {
      // ...
      maven { url "" }
      // ...

To enable VideoIdent support, uncomment the following line in node_modules/@sumsub/react-native-mobilesdk-module/android/build.gradle.

dependencies {
    implementation "com.sumsub.sns:idensic-mobile-sdk-videoident:1.31.3"




Disable bitcode for your iOS project.

  1. Add as follows at the top of ios/Podfile.
source ''
source ''

# Enable MRTDReader (NFC) module

# Enable VideoIdent module
  1. Run the following command.
npx pod-install



If it fails with CocoaPods could not find compatible versions for pod "IdensicMobileSDK" message, do as follows:

cd ios && pod update IdensicMobileSDK && cd ..
  1. Update Info.plist to have a description for the usage of the camera, microphone, photo library and geolocation:
plutil -insert "NSCameraUsageDescription" -string "Let us take a photo" ios/${PWD##*/}/Info.plist
plutil -insert "NSMicrophoneUsageDescription" -string "Time to record a video" ios/${PWD##*/}/Info.plist
plutil -insert "NSPhotoLibraryUsageDescription" -string "Let us pick a photo" ios/${PWD##*/}/Info.plist
plutil -insert "NSLocationWhenInUseUsageDescription" -string "Please provide us with your geolocation data to prove your current location" ios/${PWD##*/}/Info.plist

MRTDReader (NFC)

The MRTDReader is a module that allows the SDK to detect and read the electronic chips placed on MRTD documents via NFC.

For Android, the module comes out of the box. To enable the module for iOS, follow the instructions below:

  1. Update ios/Podfile by enabling the MRTDReader module.
# Enable MRTDReader (NFC) module
  1. Ensure the OpenSSL-Universal dependency to be included in release builds. The MRTDReader module depends on the OpenSSL-Universal internally but starting off React Native 0.67, the Flipper extension forces the OpenSSL-Universal not to be included in the Release builds, so you have to either stop using Flipper or use the following workaround.
  # Ensure `OpenSSL-Universal` dependency to be included in Release builds
    pod 'OpenSSL-Universal', :configurations => ['Debug', 'Release']
  1. Open up the iOS project in XCode.
xed ios/
  1. Turn on the Near Field Communication Tag Reading capability for your project target.
  2. Add to the application Info.plist file.
<string>Let us scan the document for more precise recognition</string>


The VideoIdent is an optional module that is required only if you are going to use the Video identification during the verification flow.

To enable the module:

  1. Update ios/Podfile.
# Enable VideoIdent module
  1. Open up the iOS project in XCode.
xed ios/
  1. Add the Background mode capability for your project target and select the Audio, AirPlay, and Picture in Picture option required for the video call not to be broken when the application goes into background.




Before launching, make sure you have configured your verification level and access token.


import SNSMobileSDK from '@sumsub/react-native-mobilesdk-module';

// ...

let launchSNSMobileSDK = () => {

  // From your backend get an access token for the applicant to be verified.
  // The token must be generated with `levelName` and `userId`,
  // where `levelName` is the name of a level configured in your dashboard.
  // The sdk will work in the production or in the sandbox environment
  // depend on which one the `accessToken` has been generated on.
  let accessToken = "your_access_token";

  let snsMobileSDK = SNSMobileSDK.init(accessToken, () => {
      // this is a token expiration handler, will be called if the provided token is invalid or got expired
      // call your backend to fetch a new access token (this is just an example)
      return fetch('', {
        method: 'GET',
      }).then(resp => {
        // return a fresh token from here
        return 'new_access_token'
    .withHandlers({ // Optional callbacks you can use to get notified of the corresponding events
      onStatusChanged: (event) => {
        console.log("onStatusChanged: [" + event.prevStatus + "] => [" + event.newStatus + "]");
      onLog: (event) => {
        console.log("onLog: [Idensic] " + event.message);
    .withLocale('en') // Optional, for cases when you need to override the system locale

  snsMobileSDK.launch().then(result => {
    console.log("SumSub SDK State: " + JSON.stringify(result))
  }).catch(err => {
    console.log("SumSub SDK Error: " + JSON.stringify(err))

The snsMobileSDK.launch() returns a Promise that will be resolved with the Result object. Use it to determine the SDK status upon its closure.

Here is an example of the result:

  "success": false,
  "status": "Failed",
  "errorType": "Unauthorized",
  "errorMsg": "Unauthorized access with accessToken=[your access token]"


Next, you are able to use the launchSNSMobileSDK(), as defined above to launch the SDK.

For example.

<Button onPress={launchSNSMobileSDK} title="Launch SumSub SDK" />


By default, once the applicant is approved the SDK will be dismissed in 3 seconds automatically. You can adjust this time interval or switch the automatic dismissal off by setting value of zero.


Also, in case you need to close the SDK programmatically, here is the what you can do.




If it is required, you can provide an email and/or phone number that will be assigned to the applicant initially.

  "email": "...",
  "phone": "..."

Preferred documents

For IDENTITY* steps, it is possible to specify the preferred country and document type to be selected automatically, bypassing the DocType Selector screen.

Note that the parameters provided will be applied only if the corresponding combination of country and idDocType is allowed at the step according to the level configuration.

  "IDENTITY2": {

Disable Google ML Kit



This is an Android-specific feature.

The SumSub SDK uses Google ML Kit face detection library if it is available with the application and builtin Android face detection otherwise. You can disable using ML Kit even if it is available.



You can customize or localize the texts used within the SDK through the MSDK Translations tool in the dashboard.

The language of the texts will be set according to the system locale, but you could override it with the locale you desire.


For a complete list of supported locales, see this article.


In addition to the MSDK Translations tool and .withLocale, you can use .withStrings option that allows you to define the strings locally.

This may be helpful for iOS apps if you would like to avoid the Wordless Oops screen that could be rendered in case the network happens to be down during the SDK initialization and force the SDK to draw the Network Oops screen instead.

  "sns_oops_network_title": "Oops! Seems like the network is down.",
  "sns_oops_network_html": "Please check your internet connection and try again.",
  "sns_oops_action_retry": "Try again",

Note that .withLocale does not affect these strings, thus it is up to you to use the required localization.


The SDK collects and sends usage data to Sumsub servers. We do not track any sensitive data. Only general usage statistics is sent to us. It includes screen navigation events, UI controls interaction events and so on.

We interpret the usage data in order to improve Sumsub. None of the data is sold or transferred to third parties, and we do not use it for advertisement.

If you still want to disable this feature, you can use the following to do this:



Various events happening along the processing could be delivered into an optional onEvent handler:

  onEvent: (event) => {
    console.log("onEvent: " + JSON.stringify(event));

Each Event has eventType and some parameters packed into payload hash, for example:

  "eventType": "StepInitiated",
  "payload": {
    "idDocSetType": "IDENTITY"

Possible events

"applicantId": "$applicantId"
The applicant $applicantId has been loaded.
"idDocSetType": "$idDocSetType"
Step $idDocSetType has been initiated.
"idDocSetType": "$idDocSetType",
"isCancelled": false

Step $idDocSetType has been fulfilled or cancelled.
"eventName": "$eventName",
"eventPayload": object
Analytics event $eventName has occurred.

Applicant Actions

To run the iOS SDK in Applicant actions mode, you need to have:

  1. A verification level with the Applicant actions type.
  2. An access token created with the userId, levelName, and externalActionId parameters.

Aside from the notes above, use the SDK the same way that you do with regular levels, but the further processing may differ depending on the action type.

The action type is configured for a particular level in the Dashboard and can be one of the following:

Additional Verification

Additional verification actions are processed completely identically to the regular level verifications. You configure and manage the SDK the same way. Nothing special is required.



The Payment methods step is not supported at the moment.

Face Auth

Face authentication actions are handled in a specific manner. The user is taken to the FaceScan (Liveness) screen directly and once the action is complete, the SDK will be automatically closed.

When an action is completed, the status will be set to ActionCompleted and the result structure would contain the actionResult field that describes the outcome of the last action invocation.

  "success": true,
  "status": "ActionCompleted",
  "actionResult": {
    "actionId": "5f77648daee05c419400c572",
    "answer": "GREEN"

An empty value of actionResult.answer means that the action was cancelled.

Action result handler

In addition, for Face Auth actions, there is an optional onActionResult handler that allows you to handle the action results upon its arrival from the backend.

The user sees the Processing... screen at this moment.

  onActionResult: (result) => {
    console.log("onActionResult: " + JSON.stringify(result));

    // you must return a `Promise` that in turn should be resolved with
    // either `cancel` to force the user interface to close, or `continue` to proceed as usual
    return new Promise(resolve => {

API Reference


An object described the outcome of the last SDK launch:

successBooleanThe boolean value indicates if there was an error on the moment the sdk is closed. Use errorType and errorMsg to see the reasons of the error if any.
statusStringSDK status.
errorTypeStringA formal reason of the error if any.
errorMsgStringA verbose error description if any.
actionResultObjectDescribes the result of the last Face Auth action's invocation if any.

While success and status are always present, the rest fields are optional.


Here is the possible SDK statuses:

ReadySDK is initialized and ready to be presented.
FailedSDK fails for some reasons (see errorType and errorMsg for details).
InitialNo verification steps are passed yet.
IncompleteSome but not all of the verification steps have been passed over.
PendingVerification is pending.
TemporarilyDeclinedApplicant has been declined temporarily.
FinallyRejectedApplicant has been finally rejected.
ApprovedApplicant has been approved.
ActionCompletedFace Auth action has been completed.

Error type

Here is the possible error types:

UnknownUnknown or no fail.
InvalidParametersAn attempt to setup with invalid parameters.
UnauthorizedUnauthorized access detected (most likely accessToken is invalid or expired and had failed to be refreshed).
InitialLoadingFailedInitial loading from backend is failed.
ApplicantNotFoundNo applicant is found for the given parameters.
ApplicantMisconfiguredApplicant is found, but is misconfigured (most likely lacks of idDocs).
InitializationErrorAn initialization error occurred.
NetworkErrorA network error occurred (the user will be presented with Network Oops screen).
UnexpectedErrorSome unexpected error occurred (the user will be presented with Fatal Oops screen).


An object that represents an event happening along the processing:

eventTypeStringEvent type.
payloadObjectEvent payload.

Action result

An object that represents the Face Auth action result:

actionIdStringFace Auth action identifier to check the results against the server.
answerStringOverall result. Typical values are GREEN, RED or ERROR.