Web SDK

The VX Web SDK unlocks the power of VX for your application. This allows you to set up your verification process one time while empowering you to dynamically change the user's Verification Experience.

Last updated 9 months ago

Web SDK

What are the steps for getting set up?

1. Create Token

In order for the document scan/upload process to work you must submit a token within the parameters of the veratadModal.

veratadModal = new veratad.modal({
token: "8dfe0180-5389-46d4-a28c-b74061d8e7c3",
});

To get a token you must make an API call with your Veratad username and password. See link below for more details.

Tokens are only valid for 6 hours. It is recommended that you get a new token on each iFrame build.

2. Include CSS, JS and iFrame

<head>
<link rel="stylesheet" href="https://vx-fe.idresponse.com/styles/style.css">
</head>

<script src="https://vx-fe.idresponse.com/js/initialize.js"></script>

<iframe allow="camera" style="display:none;" id="veratad-frame" scrolling="no"></iframe>

Full Example

This example includes all parameters, functions and methods.

<head>
<link rel="stylesheet" href="https://vx-fe.idresponse.com/styles/style.css">
</head>
<body>
<iframe allow="camera" style="display:none;" id="veratad-frame" scrolling="no"></iframe>
<script src="https://code.jquery.com/jquery-3.3.1.js" integrity="sha256-2Kok7MbOyxpgUVvAk/HJ2jigOSYS2auK4Pfzbm7uH60=" crossorigin="anonymous"></script>
<script>
$( document ).ready(function() {
  $.get( "token.php", function( data ) {
      var token = data.token;
      var veratadModal;
          $(function(){
            veratadModal = new veratad.modal({
              international: true, 
              language: "en",
              fn: "John", 
              ln: "Smith", 
              addr: "123 Main St", 
              city: "Stratford", 
              state: "CT", 
              zip: "12345", 
              dob: "19880212", 
              email: "test51598@veratad.com",
              reference: "tery745f",
              token: token,
              styleToken: "token ID",
              qr: true,
              email_fallback: false,
              bypassDesktopIntro: true
              resultMessages: {
                success:{
                    verificationSuccessTitle: "Enter Text",
                    verificationSuccessSubTitle: "Enter Text",
                  },
                failure: {
                   verificationFailureTitle: "Enter Text",
                   verificationFailureSubTitle: "Enter Text",
                 },
                error: {
                   verificationErrorTokenTitle: "Enter Text",
                   verificationErrorTokenSubTitle: "Enter Text",
                   verificationErrorAlreadyVerifiedTitle: "Enter Text",
                   verificationErrorAlreadyVerifiedSubTitle: "Enter Text",
                   verificationErrorPendingTitle: "Enter Text",
                   verificationErrorPendingSubTitle: "Enter Text",
                   verificationErrorVelocityTitle: "Enter Text",
                   verificationErrorVelocitySubTitle: "Enter Text",
                 }
              },
              additionalData: {
                value_1: "test1",
                value_2: "test2"
              },
              onOpen: function() {

              },
              onClose: function() {

              },
              onSuccess: function() {

              },
              onFailure: function() {

              },
              onEmail: function() {

              },
              onQr: function() {

              },
              onError: function() {

              },
              onErrorToken: function() {

              },
              onErrorAlreadyVerified: function() {

              },
              onErrorPending: function() {

              },
              onErrorVelocity: function() {

              },
            });
          veratadModal.open();
        });
      }, "json" );
  });
    </script>
  <script src="https://vx-fe.idresponse.com/js/initialize.js"></script>
</body>

Functions

Name

Description

onOpen()

Triggers when the modal is first opened on the page or with the open() method

onClose()

Triggers when the modal is closed by the user or with the close() method

onSuccess()

The document was successfully scanned or successfully uploaded if DCAMS+ is not active

onFailure()

The document failed the scan process or was not uploaded successfully if DCAMS+ is not active

onEmail()

The user has requested that they get an email with a link to scan.

onQr()

The user pushed the "done" button after QR scanning.

onError()

A general processing error occurred during the scan or upload process.

onErrorToken()

An invalid token was supplied

onErrorPending()

The user's document is currently in a PENDING state and they cannot submit a new document

onErrorAlreadyVerified()

The user is in a PASS state already

onErrorVelocity()

The user has already processed 3 attempts within a 24 hour period

Methods

Name

Description

open()

Open the modal. i.e. veratadModal.open();

close()

Close the modal i.e. veratadModal.close();

destroy()

Destroy the modal and all variables i.e. veratadModal.destroy()

Parameters

Parameter

Required

Type

Description

international

optional

boolean

If the upload should be treated as a non-US document. Default is false

required

string

The customer's first name

required

string

The customer's last name

addr

required

string

The customer's street address

city

required

string

The customer's city

state

required

string

The customer's state

zip

required

string

The customer's zip code

dob

required

string

The customer's Date of Birth

(YYYYMMDD format)

phone

optional

string

The customer's phone number formatted as any of the below: (555) 555-5555 555-555-5555 5555555555

required

string

The customer's email address

reference

optional

string

An arbitrary value that will be returned with the callback

token

required

string

The token for the iFrame session

styleToken

optional

string

You can create a style ID in the admin dashboard. Once created enter the value in this parameter to customize the iFrame style.

optional

boolean

If set to "true" then the user will be given a prompt to scan a QR code when they select the "Use My Phone" option when on desktop.

additionalData

optional

object

Any additional data you would like sent back with the callback POST. This can be set with any key => value pairs.

resultMessages

optional

object

See resultMessages section below for more explanation.

language

optional

string

The value should be the ISO-639-1 Code.

email_fallback

optional

boolean

The system will default to "true". If this is set to 'false" the user will never be given the option to send an email if they are having trouble with the QR. In order for this to work the "QR" attribute also needs to be set to "true".

bypassDesktopIntro

optional

boolean

The system will default to "false". If you set this attribute to "true" then the user will go direct to either the QR or Email link flow depending on your QR settings.

resultMessages

These are the messages displayed to the end user in the iFrame.

NOTE: If you do not want the user to be messaged in the iFrame you can simply run the veratadModal.close() after one of the function callbacks.

That said, If you do not customize these messages then your users that get an email link sent to them will see the defaults on the page.

The user has passed verification or successfully uploaded if DCAMS+ is not active, but storage is active.

parameter

default message

verificationSuccessTitle

Verification Success

verificationSuccessSubTitle

You have passed verification

Something went wrong and no verification was processed. There are 4 error states:

Token - the token provided in the iFrame is not valid
Already Verified - the user (based on email) has already PASSED verification
Pending - the user (based on email) is currently in a PENDING state of verification
Velocity - The user has exceeded the velocity_threshold

parameter

default message

verificationErrorTokenTitle

Bad or Expired Token

verificationErrorTokenSubTitle

This document scan instance is using a bad or expired token. Please contact customer service.

verificationErrorAlreadyVerifiedTitle

You Are Already Verified

verificationErrorAlreadyVerifiedSubTitle

You have already passed this process and are not able to upload a new document at this time. Please call Customer Service.

verificationErrorPendingTitle

Your Document is Currently Pending Manual Review

verificationErrorPendingSubTitle

Your document is currently pending manual review and you may not provide another document at this time. Please call Customer Service.

verificationErrorVelocityTitle

Too Many Attempts

verificationErrorVelocitySubTitle

You have exceeded the amount of verification attempts. Please call Customer Service.

Callback

Once a document is uploaded, the callback will fire. The callback will also fire on subsequent status updates. The email or reference values can be used to associate the upload on Veratad's side to a customer/order on your side.

You should always use the backend callback POST to get the official status of the customer/order. The frontend callback in the JS should only be used to message and route your customer on the frontend.

Set up your callback endpoint

Click the link to create your callback endpoint

Example

POST {The URL you setup}

Body

{
    "fn": "John",
    "ln": "Smith",
    "addr": "123 Main St",
    "city": "Stratford",
    "state": "CT",
    "zip": "06614",
    "dob": "19880521",
    "email": "test@veratad.com",
    "reference": "12345-test",
    "status": "PENDING",
    "additionalData": {
        "value_1": "test1",
        "value_2": "test2"
    },
    "dcams_plus": {
        "document_data": {
            "FirstName": "LOUISA",
            "LastName": "SAMPLE",
            "MiddleName": "ANNA",
            "FullAddress": "109 S FOSTER RD, BATON ROUGE, LA, 70808-0000",
            "Address": "109 S FOSTER RD",
            "City": "BATON ROUGE",
            "State": "LA",
            "Zip": "70808-0000",
            "DateOfBirth": "19720629",
            "Height": "5-08",
            "Sex": "F",
            "EyeColor": "BRN",
            "DocumentNumber": "003009381",
            "IssueDate": "20140714",
            "ExpirationDate": "20300629",
            "CountryCode": "USA", // (ISO Alpha 2 or 3)
            "DocumentType": "DRIVERS LICENSE" // other values are PASSPORT, IDENTITY CARD and UNKNOWN
        },
        "confirmation": 92480850,
        "action": "REVIEW",
        "issues": ["DOB DOES NOT MATCH DOCUMENT", "FIRST NAME DOES NOT MATCH DOCUMENT"],
        "detail": "TRANSACTION REQUIRES FURTHER ATTENTION"
    },
    "storage": {
            "success": false
      }
}

Body (When Image Return is Active)

There is a setting when a company is not using the Veratad storage system to have the document images returned via the callback. If this setting is active then the callback body will be as follows.

{
    "fn": "John",
    "ln": "Smith",
    "addr": "123 Main St",
    "city": "Stratford",
    "state": "CT",
    "zip": "06614",
    "dob": "19880521",
    "email": "test@veratad.com",
    "reference": "12345-test",
    "status": "PENDING",
    "additionalData": {
        "value_1": "test1",
        "value_2": "test2"
    },
    "dcams_plus": {
        "document_data": {
            "FirstName": "LOUISA",
            "LastName": "SAMPLE",
            "MiddleName": "ANNA",
            "FullAddress": "109 S FOSTER RD, BATON ROUGE, LA, 70808-0000",
            "Address": "109 S FOSTER RD",
            "City": "BATON ROUGE",
            "State": "LA",
            "Zip": "70808-0000",
            "DateOfBirth": "19720629",
            "Height": "5-08",
            "Sex": "F",
            "EyeColor": "BRN",
            "DocumentNumber": "003009381",
            "IssueDate": "20140714",
            "ExpirationDate": "20300629",
            "CountryCode": "USA", // (ISO Alpha 2 or 3)
            "DocumentType": "DRIVERS LICENSE" // other values are PASSPORT, IDENTITY CARD and UNKNOWN
        },
        "confirmation": 92480850,
        "issues": ["DOB DOES NOT MATCH DOCUMENT", "FIRST NAME DOES NOT MATCH DOCUMENT"],
        "detail": "TRANSACTION REQUIRES FURTHER ATTENTION"
    },
    "storage": {
            "success": false
      },
    "documents": {
        "front": "BASE 64 Encoded Image String",
        "back": "BASE 64 Encoded Image String"
    }
}

Possible Status Values

status

description

PASS

The document has passed verification

PENDING

The document is under manual review

FAIL

The document has failed verification

Last updated 9 months ago

What are the steps for getting set up?

1. Create Token

In order for the document scan/upload process to work you must submit a token within the parameters of the veratadModal.

veratadModal = new veratad.modal({
token: "8dfe0180-5389-46d4-a28c-b74061d8e7c3",
});

To get a token you must make an API call with your Veratad username and password. See link below for more details.

Tokens are only valid for 6 hours. It is recommended that you get a new token on each iFrame build.

2. Include CSS, JS and iFrame

<head>
<link rel="stylesheet" href="https://vx-fe.idresponse.com/styles/style.css">
</head>

<script src="https://vx-fe.idresponse.com/js/initialize.js"></script>

<iframe allow="camera" style="display:none;" id="veratad-frame" scrolling="no"></iframe>

Full Example

This example includes all parameters, functions and methods.

<head>
<link rel="stylesheet" href="https://vx-fe.idresponse.com/styles/style.css">
</head>
<body>
<iframe allow="camera" style="display:none;" id="veratad-frame" scrolling="no"></iframe>
<script src="https://code.jquery.com/jquery-3.3.1.js" integrity="sha256-2Kok7MbOyxpgUVvAk/HJ2jigOSYS2auK4Pfzbm7uH60=" crossorigin="anonymous"></script>
<script>
$( document ).ready(function() {
  $.get( "token.php", function( data ) {
      var token = data.token;
      var veratadModal;
          $(function(){
            veratadModal = new veratad.modal({
              international: true, 
              language: "en",
              fn: "John", 
              ln: "Smith", 
              addr: "123 Main St", 
              city: "Stratford", 
              state: "CT", 
              zip: "12345", 
              dob: "19880212", 
              email: "test51598@veratad.com",
              reference: "tery745f",
              token: token,
              styleToken: "token ID",
              qr: true,
              email_fallback: false,
              bypassDesktopIntro: true
              resultMessages: {
                success:{
                    verificationSuccessTitle: "Enter Text",
                    verificationSuccessSubTitle: "Enter Text",
                  },
                failure: {
                   verificationFailureTitle: "Enter Text",
                   verificationFailureSubTitle: "Enter Text",
                 },
                error: {
                   verificationErrorTokenTitle: "Enter Text",
                   verificationErrorTokenSubTitle: "Enter Text",
                   verificationErrorAlreadyVerifiedTitle: "Enter Text",
                   verificationErrorAlreadyVerifiedSubTitle: "Enter Text",
                   verificationErrorPendingTitle: "Enter Text",
                   verificationErrorPendingSubTitle: "Enter Text",
                   verificationErrorVelocityTitle: "Enter Text",
                   verificationErrorVelocitySubTitle: "Enter Text",
                 }
              },
              additionalData: {
                value_1: "test1",
                value_2: "test2"
              },
              onOpen: function() {

              },
              onClose: function() {

              },
              onSuccess: function() {

              },
              onFailure: function() {

              },
              onEmail: function() {

              },
              onQr: function() {

              },
              onError: function() {

              },
              onErrorToken: function() {

              },
              onErrorAlreadyVerified: function() {

              },
              onErrorPending: function() {

              },
              onErrorVelocity: function() {

              },
            });
          veratadModal.open();
        });
      }, "json" );
  });
    </script>
  <script src="https://vx-fe.idresponse.com/js/initialize.js"></script>
</body>

Functions

Name

Description

onOpen()

Triggers when the modal is first opened on the page or with the open() method

onClose()

Triggers when the modal is closed by the user or with the close() method

onSuccess()

The document was successfully scanned or successfully uploaded if DCAMS+ is not active

onFailure()

The document failed the scan process or was not uploaded successfully if DCAMS+ is not active

onEmail()

The user has requested that they get an email with a link to scan.

onQr()

The user pushed the "done" button after QR scanning.

onError()

A general processing error occurred during the scan or upload process.

onErrorToken()

An invalid token was supplied

onErrorPending()

The user's document is currently in a PENDING state and they cannot submit a new document

onErrorAlreadyVerified()

The user is in a PASS state already

onErrorVelocity()

The user has already processed 3 attempts within a 24 hour period

Methods

Name

Description

open()

Open the modal. i.e. veratadModal.open();

close()

Close the modal i.e. veratadModal.close();

destroy()

Destroy the modal and all variables i.e. veratadModal.destroy()

Parameters

Parameter

Required

Type

Description

international

optional

boolean

If the upload should be treated as a non-US document. Default is false

required

string

The customer's first name

required

string

The customer's last name

addr

required

string

The customer's street address

city

required

string

The customer's city

state

required

string

The customer's state

zip

required

string

The customer's zip code

dob

required

string

The customer's Date of Birth

(YYYYMMDD format)

phone

optional

string

The customer's phone number formatted as any of the below: (555) 555-5555 555-555-5555 5555555555

required

string

The customer's email address

reference

optional

string

An arbitrary value that will be returned with the callback

token

required

string

The token for the iFrame session

styleToken

optional

string

You can create a style ID in the admin dashboard. Once created enter the value in this parameter to customize the iFrame style.

optional

boolean

If set to "true" then the user will be given a prompt to scan a QR code when they select the "Use My Phone" option when on desktop.

additionalData

optional

object

Any additional data you would like sent back with the callback POST. This can be set with any key => value pairs.

resultMessages

optional

object

See resultMessages section below for more explanation.

language

optional

string

If no language is specified then the system will default to English. All languages from the Google Translate API are supported.

The value should be the ISO-639-1 Code.

email_fallback

optional

boolean

bypassDesktopIntro

optional

boolean

The system will default to "false". If you set this attribute to "true" then the user will go direct to either the QR or Email link flow depending on your QR settings.

resultMessages

These are the messages displayed to the end user in the iFrame.

NOTE: If you do not want the user to be messaged in the iFrame you can simply run the veratadModal.close() after one of the function callbacks.

That said, If you do not customize these messages then your users that get an email link sent to them will see the defaults on the page.

The user has passed verification or successfully uploaded if DCAMS+ is not active, but storage is active.

parameter

default message

verificationSuccessTitle

Verification Success

verificationSuccessSubTitle

You have passed verification

Something went wrong and no verification was processed. There are 4 error states:

Token - the token provided in the iFrame is not valid
Already Verified - the user (based on email) has already PASSED verification
Pending - the user (based on email) is currently in a PENDING state of verification
Velocity - The user has exceeded the velocity_threshold

parameter

default message

verificationErrorTokenTitle

Bad or Expired Token

verificationErrorTokenSubTitle

This document scan instance is using a bad or expired token. Please contact customer service.

verificationErrorAlreadyVerifiedTitle

You Are Already Verified

verificationErrorAlreadyVerifiedSubTitle

You have already passed this process and are not able to upload a new document at this time. Please call Customer Service.

verificationErrorPendingTitle

Your Document is Currently Pending Manual Review

verificationErrorPendingSubTitle

Your document is currently pending manual review and you may not provide another document at this time. Please call Customer Service.

verificationErrorVelocityTitle

Too Many Attempts

verificationErrorVelocitySubTitle

You have exceeded the amount of verification attempts. Please call Customer Service.

Callback

Set up your callback endpoint

Click the link to create your callback endpoint

Example

POST {The URL you setup}

Body

{
    "fn": "John",
    "ln": "Smith",
    "addr": "123 Main St",
    "city": "Stratford",
    "state": "CT",
    "zip": "06614",
    "dob": "19880521",
    "email": "test@veratad.com",
    "reference": "12345-test",
    "status": "PENDING",
    "additionalData": {
        "value_1": "test1",
        "value_2": "test2"
    },
    "dcams_plus": {
        "document_data": {
            "FirstName": "LOUISA",
            "LastName": "SAMPLE",
            "MiddleName": "ANNA",
            "FullAddress": "109 S FOSTER RD, BATON ROUGE, LA, 70808-0000",
            "Address": "109 S FOSTER RD",
            "City": "BATON ROUGE",
            "State": "LA",
            "Zip": "70808-0000",
            "DateOfBirth": "19720629",
            "Height": "5-08",
            "Sex": "F",
            "EyeColor": "BRN",
            "DocumentNumber": "003009381",
            "IssueDate": "20140714",
            "ExpirationDate": "20300629",
            "CountryCode": "USA", // (ISO Alpha 2 or 3)
            "DocumentType": "DRIVERS LICENSE" // other values are PASSPORT, IDENTITY CARD and UNKNOWN
        },
        "confirmation": 92480850,
        "action": "REVIEW",
        "issues": ["DOB DOES NOT MATCH DOCUMENT", "FIRST NAME DOES NOT MATCH DOCUMENT"],
        "detail": "TRANSACTION REQUIRES FURTHER ATTENTION"
    },
    "storage": {
            "success": false
      }
}

Body (When Image Return is Active)

There is a setting when a company is not using the Veratad storage system to have the document images returned via the callback. If this setting is active then the callback body will be as follows.

{
    "fn": "John",
    "ln": "Smith",
    "addr": "123 Main St",
    "city": "Stratford",
    "state": "CT",
    "zip": "06614",
    "dob": "19880521",
    "email": "test@veratad.com",
    "reference": "12345-test",
    "status": "PENDING",
    "additionalData": {
        "value_1": "test1",
        "value_2": "test2"
    },
    "dcams_plus": {
        "document_data": {
            "FirstName": "LOUISA",
            "LastName": "SAMPLE",
            "MiddleName": "ANNA",
            "FullAddress": "109 S FOSTER RD, BATON ROUGE, LA, 70808-0000",
            "Address": "109 S FOSTER RD",
            "City": "BATON ROUGE",
            "State": "LA",
            "Zip": "70808-0000",
            "DateOfBirth": "19720629",
            "Height": "5-08",
            "Sex": "F",
            "EyeColor": "BRN",
            "DocumentNumber": "003009381",
            "IssueDate": "20140714",
            "ExpirationDate": "20300629",
            "CountryCode": "USA", // (ISO Alpha 2 or 3)
            "DocumentType": "DRIVERS LICENSE" // other values are PASSPORT, IDENTITY CARD and UNKNOWN
        },
        "confirmation": 92480850,
        "issues": ["DOB DOES NOT MATCH DOCUMENT", "FIRST NAME DOES NOT MATCH DOCUMENT"],
        "detail": "TRANSACTION REQUIRES FURTHER ATTENTION"
    },
    "storage": {
            "success": false
      },
    "documents": {
        "front": "BASE 64 Encoded Image String",
        "back": "BASE 64 Encoded Image String"
    }
}

Possible Status Values

status

description

PASS

The document has passed verification

PENDING

The document is under manual review

FAIL

The document has failed verification