Plugin Response

Response States

SUCCESS: Process finished successfully

EXIT: Process terminated by the user with no errors

FAILURE: Process finished with the user's failure to pass the service requirements

ERROR : Process terminated due to an error in the builder

Note: In the case ofERROR, please check your configurations

Document verification plus - Case Handling

When using VIDVOCRResult.getData(), the returned ocrResult may include a documentVerificationPlus object. This object contains validation flags and quality signals that help you determine whether the document should be accepted, reviewed, recaptured, or rejected.

---

Fields Returned Under documentVerificationPlus

Field	Type	Meaning
frontDataValidity	boolean	Overall validity of the front side based on greyscale flags + invalid fields list
backDataValidity	boolean	Overall validity of the back side based on greyscale flags + invalid fields list
isFrontGreyscale	boolean	Indicates whether the front side is greyscale
isBackGreyscale	boolean	Indicates whether the back side is greyscale
expired	boolean	Whether the document is recognized as expired
reviewRequired	List<String>	Fields that require attention (e.g. Nid, gender, expirydate…)

---

How to Read These Values

• frontDataValidity and backDataValidity act as parent flags → You can take action directly based on them if you want a simple validation flow.

• For more control, you can check detailed signals:

  • use greyscale flags if you want to reject black-and-white copies

  • use reviewRequiredto apply different logic per field e.g. reject if nid is invalid but allow if gender is inconsistent

This allows fully customizable decision logic depending on your business rules.

Example Handling Logic

// Note:
// - All decisions are EXAMPLES only — you can adjust based on your business logic.
// - Functions such as requestRecapture(), showError(), and showRetryDialog()
//   must be implemented by you in your UI flow.

const flags = result?.nameValuePairs?.ocrResult?.ocrResult?.documentVerificationPlus;

if (flags) {

    // --------------------- GENERIC VALIDATION RESULTS --------------------- //

    // Global document validity check
    if (flags.frontDataValidity === false || flags.backDataValidity === false) {
        showRetryDialog(
            "Document failed validation checks.",
            "Please try again.",
            () => startOCR()       // developer custom restart logic
        );
    }

    // Greyscale document detection
    else if (flags.isFrontGreyscale === true || flags.isBackGreyscale === true) {
        requestRecapture("Document appears to be black & white.");
        // requestRecapture() is a custom retry handler
    }

    // Expired document
    else if (flags.isExpired === true) {
        showRetryDialog(
            "OCR",
            "Expired ID, please try again with your recent National ID.",
            () => startOCR()
        );
    }

    // Review-required fields exist
    else if (flags.reviewRequired && flags.reviewRequired.length > 0) {
        showError("Some fields require manual review.");
        // Custom function for UI display or alert message
    }


    // --------------------- FIELD-LEVEL REVIEW FLAGS --------------------- //

    if (flags.reviewRequired) {

        if (flags.reviewRequired.includes("serial_number")) {
            showRetryDialog(
                "OCR",
                "Serial number is incorrect. Please try again.",
                () => startOCR()
            );
        }

        if (flags.reviewRequired.includes("back_nid") ||
            flags.reviewRequired.includes("front_nid")) {
            requestRecapture("NID Mismatch");
        }

        if (flags.reviewRequired.includes("date_of_birth")) showError("Date of birth could not be verified.");
        if (flags.reviewRequired.includes("street")) showError("Street address is empty.");
        if (flags.reviewRequired.includes("police_station")) showError("Police station field needs review.");
        if (flags.reviewRequired.includes("governorate")) showError("Governorate value could not be verified.");
        if (flags.reviewRequired.includes("birth_governorate")) showError("Birth governorate requires review.");
        if (flags.reviewRequired.includes("expiry_date")) showError("Expiry date is missing or invalid.");
        if (flags.reviewRequired.includes("release_date")) showError("Release date did not pass validation.");
    }

    else {
        // DEFAULT — no flags triggered → document accepted
    }
}

Advance confidence - Case Handling

When using VIDVOCRResult.getData(), the returned ocrResult may include a advancedConfidence object. This object contains manipulation flags that help you determine whether the document should be accepted, reviewed, recaptured, or rejected.

---

Fields Returned Under advanceConfidence

Field	Type	Meaning
fraudDetectionZone	int	Parent zone flag → Result of face + image manipulation combined
faceFraudZone	int	Fraud confidence specifically related to face physical tampering
frontImageManipulationZone	int	Indicates signs of front image physical manpulation

Zone Meaning

Value	Color	Meaning
0	Green	No manipulation detected
1	Yellow	Requires human review (suspicious)
2	Red	Strong indicators of fraud / manipulation

---

Example Handling Logic

//Note that all decisions taken in this code are just an example of how you can handle
//the logic and that you can take the preferred action according to your business needs
const fraud = result?.nameValuePairs?.ocrResult?.ocrResult?.advancedConfidence;

// Parent Zone
if (fraud?.fraudDetectionZone === 1) showWarning("Suspicious document — needs review");// Replace with custom handling
if (fraud?.fraudDetectionZone === 2) requestRecapture("Fraud detected — retry required"); // Developer replaces with custom retry logic

// Detailed Breakdown
if (fraud?.faceFraudZone > 0) showError("Face manipulation detected");
if (fraud?.frontImageManipulationZone > 0) showError("Image manipulation detected"); // Replace with custom handling

Primary Response Object

nameValuePairs

Note: All SDK responses are returned in JSON format

Note: This is the first-level object

nameValuePairs Object Body

• state <string>

• errorCode <string>

• errorMessage <string>

• ocrResult <object>

• capturedImages list<object>

• events list<object>

• errors list<object>

ocrResult Object Body

Note: This is the second-level object that contains all third-level objects

• sessionID <string>

ocrResult <sub-object>

• firstName <string>

• fullName <string>

• religion <string>

• gender <string>

• dateOfBirth <string>

• age <int>

• maritalStatus <string>

• husbandName <string>

• street <string>

• birthGovernorate <string>

• policeStation <string>

• governorate <string>

• profession <string>

• releaseDate <string>

• expiryDate <string>

• expired <boolean> : indicates whether the NID is past its expiry date.

• serialNumber <string>

• frontNid <string>

• backNid <string>

• frontDataValidity <boolean> : data on the front side is valid or not.

• backDataValidity <boolean> : data on the back side is valid or not.

• frontConfidence <int> : indicates if the front of the document is real or fake.

• backConfidence <int> : indicates if the back of the document is real or fake.

• isRootOfTrustCompatible <boolean>

• transactionIdFront <string> : This could be used in face match in liveness sdk.

• transactionIdBack <string>

• combinationID <string>

• documentVerificationPlus <object>

  • frontDataValidity <boolean> : data on the front side is valid or not.

  • backDataValidity <boolean> : data on the back side is valid or not.

  • isFrontGreyscale<boolean>

  • backConfidence <int>

  • isBackGreyscale<boolean>

  • expired <boolean>

  • reviewRequiredArrayList<string> : an ArrayList of the names of fields that is invalid.

• advancedConfidence <object>

  • fraudDetectionZone <int>

  • fraudDetectionDetails <object>

    • faceFraudZone <int>

    • faceFraudConfidence <float>

    • frontImageManipulationZone <int>

    • frontImageManipulationConfidence <float>

documentVerificationResult <sub-object>

• success <boolean>

captures <sub-object>

• nationalIdFront <base64-string>

• nationalIdBack <base64-string>

Note: captures object contains the latest images used for the OCR service

hmacDataList <list>

• serviceID: ocr

• hmacDigest <string>

• rawResponse <string>

The raw response in hmacDataList should be mapped to the result object as per the HMAC Validation Documentation

decryptionKeys <sub-object>

• nationalIdFrontRequestKey [UInt8]

• nationalIdBackRequestKey [UInt8]

• combineResponseKey [UInt8]

Review Required Feature Breakdown:

The following are possible values that could come in the review required list along with their triggers

Review Required Possible Values

• date_of_birth triggered by an invalid date or incorrect format

• street when the field value is missing from the response

• police_station when the field value is missing from the response

• governorate when the field value is missing from the response

• birth_governorate triggered by an invalid field format

• back_nid triggered by an invalid field format

• front_nid triggered by an invalid field format

• serial_number triggered by an invalid field format

• full_name triggered when the field value is missing from the response

• first_name triggered when the field value is missing from the response

• expiry_date triggered by an invalid date or incorrect format

• release_date triggered by an invalid date or incorrect format

• front_img triggered when is_front_greyscale is true

• back_img triggered when is_back_greyscale is true

capturedImages Object Body

• nationalIDLabel <string>

• nationalIdImage <base64-string>

Note: capturedImages is a list of objects that contains all images captured throughout the experience

events Object Body

• date <string>

• key<string>

• screen <string>

• timestamp <string>

• type <string>

errors Object Body

• code<string>

• message<base64-string>

• date <string>

• screen <string>

• timestamp <string>

• type <string>

Note: events and errors objects are only returned if enable_logging is set to true from the plugin configuration

State Responses

SUCCESS

• nameValuePairs <object>

  • state <string>

  • ocrResult <sub-object>

  • capturedImages <sub-object>

  • events <sub-object>

  • errors <sub-object>

EXIT

• nameValuePairs <object>

  • state <string>

  • ocrResult <sub-object>

  • capturedImages <sub-object>

  • step <string>

  • events <sub-object>

  • errors <sub-object>

Note: step <string> identifies the point where the user chose to exit the SDK

FAILURE

• nameValuePairs <object>

  • state <string>

  • errorCode <int>

  • errorMessage <string>

  • capturedImages <sub-object>

  • ocrResult <sub-object>

  • events <sub-object>

  • errors <sub-object>

ERROR

• nameValuePairs <object>

  • state <string>

  • errorCode <int>

  • errorMessage <string>