Integration

Architecture overview

To use XpressID, the following data will be provided by Veridas:

1. "XpressID_URL", which varies depending on the environment (sandbox or production), region, etc
2. "CLIENT_ID" (unique for each client)
3. "CLIENT_SECRET" (unique for each client)

The "CLIENT_ID" and "CLIENT_SECRET" will be used to interact with XpressID Authentication API REST.

Moreover, to comply with Veridas security measures, the following information should be provided by the client:

• Client server IPs where XpressID is planned to be embedded

Note: this security measure only applies to production environments and not to the sandbox.

To have a functional XPressID service integrated in a customer infrastructure, the interaction with two elements is required:

1. Authentication API: these requests must be made from the application backend. This is the only place where the variables "CLIENT_ID" and "CLIENT_SECRET" are needed.
2. Iframe: this is where XpressID is embedded. Since it’s HTML code, it must be used in the application frontend. It’s very important not to use the variables "CLIENT_ID" and "CLIENT_SECRET" within the frontend, for security reasons.

This must be the architecture of the web application using XpressID that increases the security of onboardings.

It is also possible to have "yourGetTokenFunction()" in the frontend, however, it must send the request to the backend and the backend must redirect the request to Veridas cloud, adding the "CLIENT_ID" and the "CLIENT_SECRET":

Since XpressID does not provide any manual login step (because the authentication step is done from the backend), it is recommended to put some security measures to avoid abusive uses.

Some of these security measures could be:

• A login step before accessing XpressID
• A captcha step before accessing XpressID
• A rate limit to block multiple requests from the same IP
• DDoS mitigation measures

How to configure

The first step to embed XpressID in an iframe, is to obtain an access token.

For this purpose, XpressID Authentication API must be used to Obtain Oauth2 token.

XpressID requires some configuration parameters that define the onboarding process that will be followed by users. These configuration parameters are set by means of DATA parameter. See the section data configuration.

The second step is to invoke the XpressID URL plus the token via an iframe. See the section iframe integration

And the last step is to get the results and events that the XpressId iframe returns. See the section recieve data from iframe

Language configuration

By default, XpressID is configured in 2 languages: Spanish and English. If the browser is set to Spanish, all texts and buttons will show in Spanish. If the browser is set in English or any other language, all texts and buttons will be shown in English. To show all texts in a different language (for example Catalonian, Basque, French, etc.) It's mandatory to translate them all using the (available parameters)

Data configuration

The following defines the properties that can go into the DATA parameter, where the flowId configuration must be sent (mandatory).

Flow setup

This section contains parameters that apply to the flow configuration.

flowId

Flow that XpressID is going to use. (Mandatory to send)

• Type: String

• Default value: ""

• Possible values: "document_selfie" | "document_selfie_video" | document_selfiealive" | "document_selfiealive_video" | "document_video" | "document" | "seldoc_document_selfie" | "seldoc_document_selfie_video" | seldoc_document_selfiealive" | "seldoc_document_selfiealive_video" | "seldoc_document_video" | "seldoc_document" | "selfie" | "selfiealivepro" | "selfie_document" | "selfie_seldoc_document" | "selfiealivepro_document" | "selfiealivepro_seldoc_document"

• Example:

  flowId: "document_selfiealive_video"
  

Each possible values defines the flow XpressID will use:

• document_selfie: document validation process + selfie capture process
• document_selfie_video: document validation process + selfie capture process + video identification process
• document_selfiealive: document validation process + selfie alive capture process
• document_selfiealive_video: document validation process + selfie alive capture process + video identification process
• document_video: document validation process + video identification process
• document: document validation process
• seldoc_document_selfie: document validation process + selfie capture process
• seldoc_document_selfie_video: document validation process + selfie capture process + video identification process
• seldoc_document_selfiealive: document selection process + document validation process + selfie alive capture process
• seldoc_document_selfiealive_video: document selection process + document validation process + selfie alive capture process + video identification process
• seldoc_document_video: document selection process + document validation process + video identification process
• seldoc_document: document selection process + document validation process
• selfie: selfie capture process including passive liveness detection
• selfiealivepro: face liveness detection implemented following active liveness detection (a challenge-response schema)
• selfie_document: selfie capture process including passive liveness detection + document validation process (only available for the age verification process)
• selfie_seldoc_document: selfie capture process including passive liveness detection + document selection process + document validation process (only available for the age verification process)
• selfiealivepro_document: face liveness detection implemented following active liveness detection (a challenge-response schema) + document validation process (only available for the age verification process)
• selfiealivepro_seldoc_document: face liveness detection implemented following active liveness detection (a challenge-response schema) + document selection process + document validation process (only available for the age verification process)

documentType

Document type that will be given to the backend validation service in order to analyze the document properly. The default value is "XX", classify the front image among all the documents recognized by the general classifier.

• Type: String separated by commas

• Default value: "XX"

• Possible values: For a detailed list of all possible values, please check vali-Das documentation in section Document Type name specification.

• Example:

  documentType: "XX,XX_Passport_YYYY"
  

selfieChallenge

Optional parameter in order to activate the challenge in the selfie process. This functionality is an active liveness detection. The user needs to perform some random movements, following the indications of the challenge.

This parameter is only valid for flows that containing selfiealive.

• Type: Boolean

• Default value: false

• Possible values: false | true

• Example:

  selfieChallenge: true
  

confirm

Boolean field that must be false if you do not want the confirmation to be made and the validation to be uploaded to Boi-das. The confirmation part then falls on the client to communicate with the Vali-das service from its backend server.

• Type: Boolean

• Default value: true

• Possible values: true | false

• Example:

  confirm: true
  

scoresConfiguration

Configuration of optional scores for document validation.

• Type: object

• Default value: {}

• Possible values: see Vali-Das documentation.

• Example:

  scoresConfiguration: {
      minimumAcceptableAge: 18
  }
  

scores

boolean field that must be false if you do not want the results of the scores to be returned to the front end.

• Type: Boolean

• Default value: true

• Possible values: true | false

• Example:

  scores: true
  

contextualData

optional data that will be saved within the validation. Any data is valid and will be saved within the validation, nevertheless, data whose key begins with "stats_" will be registered in Veridas monitoring system (useful when you want to keep track of this data).

• Type: Object

• Default value: {}

• Possible values: any object. It is recommended not to use the characters " and ' inside the string fields, use ` ´ ' " ′ ″ instead.

• Example:

  contextualData: {
      contextualData1: "7746384629",
      contextualData2: "Madrid",
      stats_contextualData3: "Save this data"
  }
  

videoDocComparison

optional parameter that expects to receive a boolean value. If it is true, the videoDocComparison process will be activated when the flow has a process with document and video. This parameter does a comparison process of the photographed document with the document shown in the video process.

• Type: Boolean

• Default value: false

• Possible values: true | false

• Example:

  videoDocComparison: true
  

multipleOnboarding

This section consists of how to set up various document capture processes.

Document capture processes can go:

• All document capture processes can be with document selector or without document selector. It is not possible to set up one process with document selector and another without document selector.
• If without document selector, depending on the document types defined, the auto-classified selector can be displayed in the process that requires it.

• Type: Object

• Default value: {}

• Possible values:

Key	Type	possible values
documentsToProcess	Number	2-3
documentSelectors	Array of object	the configuration properties of the document selector
documentTypes	Array of string	see the documentType property for possible values

• Example:

  multiple onboarding by default (document selector or document types with XX based on the defined flow)

      {
          "multipleOnboarding": {
              "documentsToProcess": 2
          }
      }
  

  multiple onboarding with document selectors

  {
      "multipleOnboarding": {
          "documentsToProcess": 2,
          "documentSelectors": [
              {
                  "seldocGeolocation": true,
                  "seldocDefaultCountry": "ES",
                  "seldocCountryFilter": [
                      "ES",
                      "MX"
                  ],
                  "seldocTypeFilter": [
                      "IDCard",
                      "DrivingLicense"
                  ]
              },
              {
                  "seldocGeolocation": false,
                  "seldocDefaultCountry": "IT",
                  "seldocCountryFilter": [
                      "ES",
                      "IT"
                  ],
                  "seldocTypeFilter": [
                      "IDCard"
                  ]
              }
          ]
      }
  }
  

  multiple onboarding without document selector and document types

    {
        "multipleOnboarding": {
            "documentsToProcess": 3,
            "documentTypes": [
                "ES2_ID,IT_ID,XX_Passport_YYYY",
                "ES2_ID",
                "ES2_DL"
            ]
        }
    }
  

QR setup

This section consists of displaying a QR to redirect end users to mobile. This functionality only applies to desktop devices.

The process is that the end user captures the QR from the mobile and is redirected to that URL. In this way the end user can continue the process from the mobile with a more optimal capture.

In order to continue the process from the mobile it is necessary for the integrator to apply its management logic to load the same onboarding process previously requested on desktop.

By default, the QR is not displayed on the desktop, to activate the QR process you have to set the parameter mobileQrRedirect.

For a detailed explanation of a QR setup use case, please refer How to redirect onboardings from desktop to mobile using QR redirection.

mobileQrRedirect

optional parameter that expects to receive a URL from which a QR.

• Type: String

• Default value: ""

• Possible values: any String. It is recommended not to use the characters " and ' inside the string fields, use ` ´ ' " ′ ″ instead.

• Example:

  mobileQrRedirect: "https://yourDomain.com"
  

mobileQrParams

optional parameters for the URL that forms the QR, these parameters are added to the URL as GET parameters.

• Type: object

• Default value: {}

• Possible values: any object. It is recommended not to use the characters " and ' inside the string fields, use ` ´ ' " ′ ″ instead. It is also not necessary to encode the params, it accepts special characters such as "=", "%", "/", etc.

• Example:

  mobileQrParams: {
      "sessionid": "1672632",
      "language": "es"
  }
  

  If we use this parameter together with the previous one (mobileQrRedirect) we get an URL like this:

  https://yourDomain.com/?sessionid=1672632&language=es
  

The above URL will be used to generate a QR to redirect the user to that URL.

disableContinueOnDesktop

optional parameter for disabling the 'Continue on Desktop' functionality QR.

• Type: Boolean

• Default value: false

• Possible values: false | true

• Example:

  disableContinueOnDesktop: true
  

Resume process setup

The following parameter is used to query if there is pending process to be done, in case there is process at the time of authentication API returns a new token for the same validation. See the section Obtain Oauth2 token responses.

validationId

ValidationId of an onboarding process, if a validation is indicated it checks if the onboarding process is pending completion to continue from where the end-user left off.

• Type: String

• Default value: ""

• Possible values: A validationId used before for an onboarding process.

• Example:

  validationId: "7e85d728a0574754984837e5ba783cec"
  

Document selector setup

seldocCountryFilter

optional filter for document selector so just specified countries are listed.

• Type: array

• Default value: all countries listed

• Possible values: Comma-separated list of any of possible ISO 3166-1 alfa-2 codes.

• Example:

  seldocCountryFilter: [
      "ES",
      "IT",
      "MX",
      "CA",
      "US"
  ],
  

seldocTypeFilter

optional filter for document selector so just specified types are listed.

The value of AnyCard is used to indicate the capture of any type of document (IDCard, DrivingLicense, HealthCard and ProfessionalCard) from the selected country.

• Type: array

• Default value: ["IDCard", "DrivingLicense", "HealthCard", "ProfessionalCard", "Passport", "XX_XX_XXXX"]

• Possible values: Comma-separated list of possible "IDCard" || "DrivingLicense" || "HealthCard" || "ProfessionalCard" || "Passport" || "XX_XX_XXXX" || "AnyCard".

  The AnyCard value can only be sent as ["AnyCard"] || ["AnyCard", "Passport"] || ["AnyCard", "Passport", "XX_XX_XXXXXX"], the combination with the other values is wrong.

  Note: The IDCard value includes the following types of document: IDCard, ResidencePermit, IDCard-PO, IDCard-MilitaryRS, IDCard-MilitaryRT, IDCard-MilitaryRR.

• Example:

  seldocTypeFilter: [
      "IDCard",
      "DrivingLicense"
  ],
  

seldocGeolocation

Boolean field that enables and disables geolocation in document selector.

• Type: Boolean

• Default value: true

• Possible values: true | false

• Example:

  seldocGeolocation: false
  

seldocDefaultCountry

This field set document selector default selected country (if present).

• Type: string

• Default value: 'ES'

• Possible values: One value of any of possible ISO 3166-1 alfa-2 codes.

• Example:

  seldocDefaultCountry: 'MX'
  

Autoclassification document selector setup

This type of selector is set up when aiming to simplify the choices to just two options: passport or any other type of identification document.

The way to configure this selector is by including the passport option and any other identification documents, such as IDs or driver's licenses, in the parameter "documentType".

• Example:

  {"flowId": "document", "documentType": "ES_IDCard_2015,XX_Passport_YYYY"}
  

Receive data at the front end

callbackData

optional user data with some fields that may be used in the return data step. The return values are:

- `ocr`: return all data scanned from the document as a JSON format.

- `completeScores`: return all complete scores availables, (by default "Score-DocumentGlobal", "ValidasScoreSelfie", "ValidasScoreLifeProof", "ValidasScoreVideo", "ValidasScoreIntegrity" and "ValidationGlobalScore") as JSON format.

- `reverseImage`: return the reverse image of the document in base64,

- `obverseImage`: return the obverse image of the document in base64.

- `selfieImage`: return the selfie image in in base64.

• Type: object

• Default value: {"ocr": false, "completeScores": false, "reverseImage": false, "obverseImage": false, "selfieImage": false}

• Possible values: {"ocr": true | false, "completeScores": true | false, "reverseImage": true | false, "obverseImage": true | false, "selfieImage": true | false} as a object.

• Example:

  callbackData: {
      ocr: true,
      selfieImage: true
  }
  

Politically Exposed Persons (PEP) & Adverse Media setup

Here is an explanation of what PEP and Adverse Media is.

pepAndAml

optional parameter for activating the PEP & AML.

• Type: Boolean

• Default value: false

• Possible values: false | true

• Example:

  pepAndAml: true
  

Third Party Identity Verification setup

Validate a document with a third party identity verification service (Spanish Data Verification and Consultation Service, AAMVA)

identityVerification

Parameter	Type	Default value	Example
identityVerification	object	{}	{"identityVerification":{"service":"ESMinistry", "applicationCode":"xxxxxxx"}}
identityVerification	object	{}	{"identityVerification":{"service":"AAMVA"}}

Schema of configuration

{
   identityVerification: {
      type: "object",
      properties: {
         service: {
            type: "string",
            enum: ["AAMVA","ESMinistry"]
         },
         applicationCode: {
            type:"string" (required when usign ESMinistry)
         }
      },
      required: ["service"]
   }
}

timestamp setup

timestamp

optional parameter for activating the timestamp of the evidences, check the other parameters timestampRequiredand timestampAuthority.

• Type: Boolean

• Default value: false

• Possible values: false | true

• Example:

  timestamp: true
  

timestampRequired

optional parameter that is just applied if the timestamp parameter is active. This parameter makes the timestamping process mandatory. This means that the process can not be confirmed until the timestamp process is done successfully, so, if the timestamping process fails, the end user must repeat the identity verification process. By default this parameter is not activated which means that if the timestamp fails, the process is confirmed.

• Type: Boolean

• Default value: false

• Possible values: false | true

• Example

  timestampRequired: true
  

timestampAuthority

optional parameter that is applied if the timestamp parameter is active, this parameter allows to indicate the Timestamp authority (TSA) which wants to be used for the timestamping process. By default, the evidences will be time stamped with the TSA named "standard", which is a non-SLA / no-production-ready TSA.

• Type: String

• Default value: ""

• Possible values: "fnmt" || "standard" || "izenpe"

• Example:

  timestampAuthority: "standard"
  

Authentication setup

The authentication process involves verifying the identity of a user through the submission of a selfie. The authentication process may be used for either enrolment or authentication. This process is initiated when the authentication parameter is set to a dictionary containing the method key with a value of either enrol or auth, depending on the desired process.

Action	Type	Default Value	Example
enrolment	Object	{}	{ authentication: { method: "enrol" } }
authentication	Object	{}	{ authentication: { method: "auth", selfie: "BASE64 IMAGE" } }

Age Verification setup

The age verification process consists of verifying the age of a user by submitting a selfie. This process is initiated when the ageVerification parameter is set to a dictionary containing the ageThreshold key with a value between 18 and 21, depending on the desired process.

Valid flows to validate selfie only are: selfie and selfiealivepro.

Valid flows to validate selfie plus document are: selfie_document, selfie_seldoc_document, selfiealivepro_document and selfiealivepro_seldoc_document.

• Type: object

• Default value: {}

• Possible values: {"ageThreshold": 18 | 19 | 20 | 21 } as a object.

• Example:

  ageVerification: {
      ageThreshold: 18,
  }
  

UI/UX setup

configData

with this data it’s possible to customize texts, colors and some XpressID configuration parameters. Please check the SDK HTML Capture Process - Configuration where the different customisable parameters of the Document, Selfie, Selfie Alive and Video SDKs are specified**.

Example passing data to obtain a token

When XpressID iframe is being embedded, it will automatically load with the data previously passed when requesting the access token.

This eases the integration process and constitute a security measure since configuration is not exposed from the FRONT side.

Examples of passing data via authentication API as data JSON parameter with recommended UI are:

Document + SAP case

{
    "contextualData": {
        "id": "1234567890",
        "region": "Madrid"
    },
    "documentType": "ES2_ID",
    "flowId": "seldoc_document_selfiealive",
    "configData": {
      "continueText": "Continue",
      "repeatText": "Repeat",
      "detectionMessageBackgroundColor": "#000D44",
      "detectionMessageTextColor": "#FFFFFF",
      "confirmationDialogBackgroundColor": "#ffffff",
      "confirmationColorTick": "#078B3C",
      "confirmationDialogTextColor": "#000D44",
      "confirmationDialogButtonTextColor": "#FFFFFF",
      "confirmationCaptureButtonBackgroundColor": "#000D44",
      "confirmationRepeatButtonTextColor": "#000D44",
      "confirmationRepeatButtonBackgroundColor": "transparent",
      "outerGlowCenteringAidDefault": "#000D44",
      "outerGlowCenteringAidDetecting": "#000D44",
      "infoUserDocumentBackgroundColorTop": "#000D44",
      "infoUserDocumentBackgroundColor": "#ffffff",
      "infoUserDocumentTextColor": "#000D44",
      "infoUserDocumentBackgroundColorButton": "#000D44",
      "infoUserDocumentTextColorButton": "#ffffff",
      "infoUserDocumentBorderColor": "#000D44",
      "infoReviewImageTextDocument": "Check that all data in the document is clearly readable and that there are no glares",
      "sdkBackgroundColorInactive": "#ffffff",
      "iframeLoaderColor": "#FF7777",
      "iframeLoaderBackgroundColor": "#FFFFFF",
      "iframeLoaderTextColor": "#FFFFFF",
      "iframeBackgroundColor": "#000D44",
      "iframeCheckTextColor": "#000D44",
      "iframeCheckBorderColor": "#078B3C",
      "iframeCheckTickColor": "#078B3C",
      "infoUserAliveHeaderColor": "#000D44",
      "infoUserAliveBackgroundColor": "#ffffff",
      "infoUserAliveNextButtonColor": "#000D44",
      "infoUserAlivePrevButtonColor": "#000D44",
      "infoUserAliveTitleColor": "#000D44",
      "infoUserAliveSubTitleColor": "#000D44",
      "infoUserAliveColorButton": "#000D44",
      "infoUserAliveHeader": " ",
      "infoUserAliveSubTitle": [
              "1. Place your face in the center of the oval and wait for the countdown." ,
              "2. Rotate your face in the direction indicated by the arrows." ,
              "3. Continue the movements until the process is complete."
      ],
      "stepsChallengeColor": "#000D44",
      "buttonBackgroundColorDarkRepeat": "transparent",
      "buttonBackgroundColorLightRepeat": "transparent",
      "buttonBackgroundColorDark": "#000D44",
      "buttonBackgroundColorLight": "#000D44",
      "repeatButtonColor": "#000D44",
      "errorActionButtonTextColor": "#000D44",
      "errorDisplayTextColor": "#000D44",
      "errorDisplayBackgroundColor": "#ffffff",
      "errorDisplayIconColor": "#000D44",
      "borderColorCenteringAidDetecting": "#078B3C",
      "iframeInitialColor": "#FFFFFF",
      "iframeEndColor": "#FFFFFF",
      "iframeTextColorQr": "#00051A",
      "iframeQrButtonTextColor": "#000D44",
      "iframeSeldocMainColor": "#00051A",
      "iframeSeldocSecondaryColor": "#00051A"
    },
    "selfieChallenge": true,
    "callbackData": {
        "ocr" : true,
        "reverseImage": true,
        "obverseImage": true,
        "selfieImage": true
    },
    "mobileQrRedirect": "https://yourDomain.com",
    "mobileQrParams": {
        "sessionid" : "1672632",
        "language" : "es"
    },
    "timestamp": true,
    "timestampRequired": false,
    "timestampAuthority": "standard",
    "scoresConfiguration": {
        "minimumAcceptableAge": 18
    },
    "scores": false,
    "confirm": false,
    "seldocCountryFilter": [
        "ES",
        "IT",
        "MX",
        "CA",
        "US"
    ]
}

Document + SAP + Video case

{
    "contextualData": {
        "id": "1234567890",
        "region": "Madrid"
    },
    "documentType": "ES2_ID",
    "flowId": "document_selfiealive_video",
    "configData": {
      "continueText": "Continue",
      "repeatText": "Repeat",
      "detectionMessageBackgroundColor": "#000D44",
      "detectionMessageTextColor": "#FFFFFF",
      "confirmationDialogBackgroundColor": "#ffffff",
      "confirmationColorTick": "#078B3C",
      "confirmationDialogTextColor": "#000D44",
      "confirmationDialogButtonTextColor": "#FFFFFF",
      "confirmationCaptureButtonBackgroundColor": "#000D44",
      "confirmationRepeatButtonTextColor": "#000D44",
      "confirmationRepeatButtonBackgroundColor": "transparent",
      "outerGlowCenteringAidDefault": "#000D44",
      "outerGlowCenteringAidDetecting": "#000D44",
      "infoUserDocumentBackgroundColorTop": "#000D44",
      "infoUserDocumentBackgroundColor": "#ffffff",
      "infoUserDocumentTextColor": "#000D44",
      "infoUserDocumentBackgroundColorButton": "#000D44",
      "infoUserDocumentTextColorButton": "#ffffff",
      "infoUserDocumentBorderColor": "#000D44",
      "infoReviewImageTextDocument": "Check that all data in the document is clearly readable and that there are no glares",
      "sdkBackgroundColorInactive": "#ffffff",
      "iframeLoaderColor": "#FF7777",
      "iframeLoaderBackgroundColor": "#FFFFFF",
      "iframeLoaderTextColor": "#FFFFFF",
      "iframeBackgroundColor": "#000D44",
      "iframeCheckTextColor": "#000D44",
      "iframeCheckBorderColor": "#078B3C",
      "iframeCheckTickColor": "#078B3C",
      "infoUserAliveHeaderColor": "#000D44",
      "infoUserAliveBackgroundColor": "#ffffff",
      "infoUserAliveNextButtonColor": "#000D44",
      "infoUserAlivePrevButtonColor": "#000D44",
      "infoUserAliveTitleColor": "#000D44",
      "infoUserAliveSubTitleColor": "#000D44",
      "infoUserAliveColorButton": "#000D44",
      "infoUserAliveHeader": " ",
      "infoUserAliveSubTitle": [
              "1. Place your face in the center of the oval and wait for the countdown." ,
              "2. Rotate your face in the direction indicated by the arrows." ,
              "3. Continue the movements until the process is complete."
      ],
      "stepsChallengeColor": "#000D44",
      "buttonBackgroundColorDarkRepeat": "transparent",
      "buttonBackgroundColorLightRepeat": "transparent",
      "buttonBackgroundColorDark": "#000D44",
      "buttonBackgroundColorLight": "#000D44",
      "repeatButtonColor": "#000D44",
      "errorActionButtonTextColor": "#000D44",
      "errorDisplayTextColor": "#000D44",
      "errorDisplayBackgroundColor": "#ffffff",
      "errorDisplayIconColor": "#000D44",
      "borderColorCenteringAidDetecting": "#078B3C",
      "infoUserVideoBackgroundColor": "#ffffff",
      "infoUserVideoBackgroundColorTop": "#000D44",
      "infoUserVideoBackgroundColorButton": "#000D44",
      "infoUserVideoTextColorButton": "#ffffff",
      "errorBoxTextColor":"#000D44",
      "errorBoxButtonTextColor":"#000D44",
      "errorBoxBackgroundColor": "#FFFFFF",
      "errorBoxButtonColor": "#FFFFFF"
    },
    "selfieChallenge": true,
    "callbackData": {
        "ocr" : true,
        "reverseImage": true,
        "obverseImage": true,
        "selfieImage": true
    },
    "mobileQrRedirect": "https://yourDomain.com",
    "mobileQrParams": {
        "sessionid" : "1672632",
        "language" : "es"
    },
    "timestamp": true,
    "timestampRequired": false,
    "timestampAuthority": "standard",
    "scoresConfiguration": {
        "minimumAcceptableAge": 18
    },
    "scores": false,
    "confirm": false,
    "seldocCountryFilter": [
        "ES",
        "IT",
        "MX",
        "CA",
        "US"
    ]
}

Iframe integration

Once the access token is obtained, the iframe can be embedded into the HTML code in this way:

<iframe
    id="XpressID-iframe"
    allow="camera; microphone; geolocation;"
    src="https://XpressID_URL?access_token=ACCESS_TOKEN">
</iframe>

Another example, the iframe can be embedded into the REACT code in this way:

const render = messages => {
    ReactDOM.render(
        <Provider store={store}>
            <LanguageProvider messages={messages}>
                <ConnectedRouter history={history}>
                <iframe style="height:500px; width:500px;" src="https://XpressID_URL?access_token=ACCESS_TOKEN"></iframe> <App />
                </ConnectedRouter>
            </LanguageProvider>
        </Provider>,
    MOUNT_NODE,
    );
};

Note that since it’s an iframe, there is no problem related to CORS (cross-origin resource sharing) and the XpressID URL can be embedded directly into the iframe itself.

This is the only needed code in order to make XpressID to work properly. Note that ACCESS_TOKEN is unique for each final user and it’s going to be different every time XpressID is embedded.

The next point is an optional step because it depends on the use case, it consists of adjusting the iframe to screen size.

If you want to adjust the iframe size so that it takes up the whole screen, it’s a good practice to set the width and the height of the iframe to 100%. This works quite well, however, sometimes it’s necessary to do an additional step because some browsers (such as Safari mobile) may experience problems.

Moreover, it’s recommended to control the resize/rotation of the screen with an "EventListener". So to do this, we propose this cross-browser and easy-to-implement solution:

<html>
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    </head>
    <body>
        <iframe
            id="XpressID-iframe"
            allow="camera; microphone; geolocation;"
            style="width:100%;height:100%;"
            src="https://XpressID_URL?access_token=ACCESS_TOKEN">
        </iframe>
        <script type="text/javascript">
            (function() {
                adjustIframeDimensions();
                addEventListener('resize', adjustIframeDimensions);
            })();
            function adjustIframeDimensions() {
                var browser = navigator.userAgent.toLowerCase();
                if (browser.indexOf('safari')>-1 && browser.indexOf('mobile')>-1){ document.getElementsByTagName('html')[0].style.height = '100vh'; setTimeout(() => {
                    document.getElementsByTagName('html')[0].style.height = '100%'; }, 500);
                }
            }
        </script>
    </body>
</html>

Receiving data from iframe

When the process is over, a postMessage is sent by XpressID to the parent website where it has been embedded. If desired, it is possible to listen to that message with an event listener:

window.addEventListener("message", receiveMessage, false);
function receiveMessage(event) {
    if(event.origin.includes("xpressid") && event.data.code == "ProcessCompleted") {
        var dataFromXpressID = event.data;
        // do something
    }
    if(event.origin.includes("xpressid") && event.data.code == "ProcessError") {
        // do something
    }
}

For correct use of events the event listener must be invoked prior to loading XpressID. We recommend first adding the listener to the iframe first and then replacing the src property of the iframe with the value of https://XpressID_URL?access_token=ACCESS_TOKEN.

This event returns some important data ("validationId" and "globalScores") and indicates that XpressID process has been successfully completed.

Throughout the process, XpressID needs to send some data to the parent website where it’s embedded. This data can be of two types:

• Informational data
• Error data

Note that with the "event.origin.includes("xpressid")" directive we ensure the event comes from XpressID, otherwise, the event could be coming from another part of the website.

The returned data ("dataFromXpressID" in the example), will always have the same structure: it’s a JavaScript object with these fields:

Name	Req.	Type	Description
code	yes	string	unique event code
type	yes	string	event type. Only two available values: "info" (for informational data) and "error" (for error data)
message	yes	string	event text explanation
additionalData	no	string or json	additional data that only exists in some certain events

To distinguish between the different messages, it is necessary to check the "event.data.code".

response

code	type	message	additionalData
ProcessCompleted	info	The process has been successfully completed	json value. See the section ProcessCompleted
BrowserNotSupported	error	Not supported browser. You must repeat the process:\n If you are on an iPhone you must use the Safari browser.\n In all other cases you can use Chrome, Firefox or Opera.
ProcessError	error	Error in the process	string value where process fails. See the section ProcessError

Informational data

This is the event that send informational data to the parent website where XpressID is embedded.

ProcessCompleted

This event occurs when the XpressID process has just been completed successfully. The structure of the received data is:

{
    type: "info",
    code: "ProcessCompleted",
    message: "The process has been successfully completed",
    additionalData: {
        validationId: VALIDATION_ID,
        globalScores: JSON_GLOBAL_SCORES,
        ocr: JSON_OCR_DATA,
        obverseImage: STRING_BASE64_OBVERSE_IMAGE,
        reverseImage: STRING_BASE64_REVERSE_IMAGE,
        selfieImage: STRING_BASE64_SELFIE_IMAGE
    }
}

Where validationId is the ID that the backend validation service uses to identify the validation and globalScores has a JSON which contains the final scores ("Score-DocumentGlobal", "ValidasScoreSelfie", "ValidasScoreLifeProof", "ValidasScoreVideo", "ValidasScoreIntegrity" and "ValidationGlobalScore") obtained on the validation process and returned by the backend validation service. If the "callbackData" parameter is configured with "completeScores", "ocr", "reverseImage", "obverseImage" and "SelfieImage" mentioned in section Receiving data from iframe, the results available in "addionalData" will appear.

Definition of the results of the additionalData parameter:

• validationdId: This parameter always is returned.

  • TYPE: STRING
  • EXAMPLE: bc15187dd51b4f43a7ec668c53b54f15

• globalScores: By default this parameter always returns the keys ("Score-DocumentGlobal", "ValidasScoreSelfie", "ValidasScoreLifeProof", "ValidasScoreVideo", "ValidasScoreIntegrity" and "ValidationGlobalScore") but if the parameter 'completeScores’ is set as in section callbackData configuration then all scores are returned. If the parameter scores is set to false in the new method the value of globalScores can be null. With the result of the scores in section Recommended scores it is recommended how to deal with the information.

  • TYPE: JSON or null.

• ocr (optional): This parameter is optional, if it is not set a "True" as in callbackData configuration then it returns a "null" otherwise it returns all ocr data in JSON format.

  • TYPE: JSON or null.

• obverseImage (optional): This parameter is optional, if not set to "True" as in callbackData configuration then it returns a "null" otherwise it returns the obverse side of the document in BASE64 format.

  • TYPE: STRING or null.
  • EXAMPLE: "data:image/jpeg;base64,/9j/4RiDRXhpZgAATU0AKgA…"

• reverseImage (optional): This parameter is optional, if not set to "True" as in callbackData configuration then it returns a "null" otherwise it returns the reverse side of the document in BASE64 format if the type of document has a reverse.

  • TYPE: STRING or null.
  • EXAMPLE: "data:image/jpeg;base64,/9j/4RiDRXhpZgAATU0AKgA…"

• selfieImage (optional):This parameter is optional, if not set to "True" as in callbackData configuration then it returns a "null" otherwise it returns the selfie capture in BASE64 format.

  • TYPE: STRING or null.
  • EXAMPLE: "data:image/jpeg;base64,/9j/4RiDRXhpZgAATU0AKgA…"

ProcessEvents

This event occurs throughout the process and provides information about what is happening:

{
        type: "info",
        code: "ProcessEvents",
        message: "Information in the process",
        infoEvent: {
                        code: "DocumentProcessStarted",
                        detail: "Document capture process has been started.",

                   }
}

In the following tables appears all the events are provided by Xpressid during the process.

QR Process

infoEvent.code	type	infoEvent.detail
QRProcessStarted	info	QR process started.
QRContinueOnDesktop	info	Clicked the continue button on the desktop.
QRProcessFinished	info	QR process finished.

Document Selector Process

infoEvent.code	type	infoEvent.detail
SelectorProcessStarted	info	Started document selector by country.
ClickOnDocumentSelector	info	Clicked any document option of the selector.
SelectorProcessFinished	info	Finished document selector by country.

Document AutoSelector Process

infoEvent.code	type	infoEvent.detail
ACSelectorProcessStarted	info	Started autoclassification selector.
ClickOnDocumentACSelector	info	Clicked one of the optioncs of the acselector.
ACSelectorProcessFinished	info	Finished autoclassification selector.

Document Process

infoEvent.code	type	infoEvent.detail
DocumentProcessStarted	info	Document capture process has been started.
DocumentMounted	info	Document capture process has been prepared.
DocumentCameraStarted	info	The camera has been started in the document process.
DocumentObverseDetection	info	The obverse of the document has been captured.
DocumentReverseDetection	info	The reverse of the document has been captured.
DocumentUnmounted	info	Document capture process has been finished.
DocumentProcessFinished	info	Document capture process has been finished.
DocumentRepeatClicked	info	The document capture process has been repeated.
DocumentcameraFailure	warning	There was a problem starting the camera in the document process.
DocumentTrackEnded	warning	There was a problem with the camera in the document process.
DocumentCheckSecurityError	warning	Possible video injection detected.
DocumentMountFailure	error	Document capture process initialization has failed.
DocumentDetectionTimeout	error	Timeout has been exceeded.

Selfie Process

infoEvent.code	type	infoEvent.detail
SelfieProcessStarted	info	Selfie capture process has been started.
SelfieMounted	info	Selfie capture process has been prepared.
SelfieCameraStarted	info	The camera has been started in the selfie process.
SelfieFaceDetection	info	Face has been successfully captured in selfie process.
SelfieRepeatClicked	info	The selfie capture process has been repeated.
SelfieUnmounted	info	Selfie capture process has been finished.
SelfieProcessFinished	info	Selfie capture process has been finished.
SelfieCameraFailure	warning	There was a problem starting the camera in the selfie process.
SelfieMountFailure	error	Selfie capture process initialization has failed.
SelfieDetectionTimeout	error	Timeout has been exceeded in selfie process.

SelfieAlive Process

infoEvent.code	type	infoEvent.detail
AliveProcessStarted	info	SelfieAlive capture process has been prepared.
AliveMounted	info	SelfieAlive capture process has been started.
AliveCameraStarted	info	The camera has been started in the selfiealive process.
AliveFaceDetection	info	Face has been successfully captured in selfiealive process.
AliveRepeatClicked	info	SelfieAlive capture process has been repeated.
AliveModelLoaded	info	Face emotion detected during the selfiealive process.
AliveUnmounted	info	SelfieAlive capture process has been finished.
AliveProcessFinished	info	SelfieAlive capture process has been finished.
AliveCameraFailure	warning	There was a problem starting the camera in the selfiealive process.
AliveMountFailure	error	Selfiealive capture process initialization has failed.
AliveDetectionTimeout	error	Timeout has been exceeded in selfiealive process.

SelfieAlivePro Process

infoEvent.code	type	infoEvent.detail
AliveProcessStarted	info	SelfieAlive capture process has been prepared.
AliveMounted	info	SelfieAlive capture process has been started.
AliveCameraStarted	info	The camera has been started in the selfiealive process.
AliveFaceDetection	info	Face has been successfully captured in selfiealive process.
AliveRepeatClicked	info	SelfieAlive capture process has been repeated.
AliveRestartChallenge	info	The challenge has been restarted.
AliveUnmounted	info	SelfieAlive capture process has been finished.
AliveProcessFinished	info	SelfieAlive capture process has been finished.
AliveCameraFailure	warning	There was a problem starting the camera in the selfiealive process.
AliveMountFailure	error	Selfiealive capture process initialization has failed.
AliveDetectionTimeout	error	Timeout has been exceeded in selfiealive process.

Video Process

infoEvent.code	type	infoEvent.detail
VideoProcessStarted	info	Video capture process has been prepared.
VideoMounted	info	Video capture process has been started.
VideoCameraStarted	info	The camera has been started in the video process.
VideoStandardVideoRecorderStart	info	Face has been successfully captured in video process.
VideoFaceDetection	info	Starting recording the video.
VideoObverseDetection	info	The obverse detection of the document has been started in video process.
VideoReverseDetection	info	The reverse detection of the document has been started in video process.
VideoRestartToken	info	Restarting video process because a document capture timeout has occurred.
VideoUnmounted	info	Video capture process has been finished.
VideoProcessFInished	info	Video capture process has been finished.
VideoCameraFailure	warning	There was a problem starting the camera in the video process.
VideoStandardVideoRecorderStop	warning	An error occurred while recording the video.
VideoMountFailure	error	Video capture process initialization has failed.
VideoDetectionTimeout	error	Timeout has been exceeded in video process.

Error data

When an error occurs, XpressID tries to handle it so that it is transparent to the user. However, there are certain errors which can not be handled by XpressID. In these cases, it will display an error message to the user, and send a message to the parent website via postMessage.

Note that although the error code is immutable, some error messages can be customized.

Here below there is a list with all unhandled errors.

BrowserNotSupported

This error occurs when the browser doesn’t support it. The structure of the received data is:

{
    type: "error",
    code: "BrowserNotSupported",
    message: "Not supported browser. You must repeat the process:\n If you are on an iPhone you must use the Safari browser.\n In all other cases you can use Chrome, Firefox or Opera."
}

ProcessError

This error occurs when the process fails either because the document or the selfie or video could not be processed, preventing the end user from continuing. This event must be captured to reload the Iframe with a new token and therefore with a new validation. The value of additionalData indicates at which point the process has failed. It can represent the values of document, selfiealive ,video and connection (when the service fails).

{
    type: "error",
    code: "ProcessError",
    message: "Error in the process",
    additionalData: "document",
}

An additional errorData optional parameter is included here for those errors where a more detailed explanation is required.

For example, when the token has expired and the iFrame XpressID is started, it returns the ProcessError event with the detailed message that the token has expired.

{
    type: "error",
    code: "ProcessError",
    message: "Error in the process",
    errorData: {
        errorCode: "TokenNotAllowed",
        errorDetail: "Token has been expired"
        flow: ""
        statusCode: 403
    }
}

Errors that may occur in the analysis of the process (uploading of documents, selfie, video) are also added.

errorCode	errorDetail	Causes of
ValidationError	"The provided data is not valid"	This error appears when any configuration of input request is incorrect. For example, a document type that does not
ErrorProcessingRequest	"Processing previous request"	This error ocurrs when the previous image is being processed and has not been completed. i.e. Sending the reverse when the obverse has not finished.
ErrorUpdateValidation	"Validation deleted during processing"	This error ocurrs if the validation is deleted while the process is still active
UnknownDocumentTypeError	"Document Analysis error: The provided image could not be classified. Please verify that the image and the document type are correct."	This error occurs when the classification method can not classify the document in image under the configuration conditions of document type. For example if a real ES_IDCard_2015 is sent ValiDas under document_type MX. The error is generic and occurs when using the "PUT document ".
	"Obverse Document Analysis error: The provided image could not be classified. Please verify that the image and the document type are correct."	This error occurs when the classification method can not classify the document in image under the configuration conditions of document type. For example, if a real ES_IDCard_2015 is sent ValiDas under document_type MX. This error is returned when all the documents have been sent in the POST, and the obverse has failed.
UnknownAnalysisTypeError	"Unknown analysis type"	"analysisType" parameter is not correctly definied. "analysisType" should be "obverse" or "reverse"
InvalidData	Invalid json data	The JSON data is not valid.
ScoresConfigurationNotAllowed	"ScoresConfiguration field is just allowed in obverse analysis"	"ScoresConfiguration" field is just allowed in obverse analysis"
ScoresConfigurationError	"Scores configuration has an incorrect value"	This error occurs when the configuration levers contain any lever with an incorrect value. For example if configuration contains "ScoreGroup-PhotoAuthenticity": 2.5
InvalidScoresConfigurationField	ScoresConfiguration field contains invalid JSON	ScoresConfiguration field contains invalid JSON
UnallowedLeversError	"Document Analysis error: The following levers could not be found please check for errors"	This error occurs when the configuration levers contain any lever that does not exist or misspelled. For example if configuration contains "ScoreGroup-PhotoAAuthenticity": 1. The error is generic and occurs when using the "PUT document ".
	"Obverse Document Analysis error: The following levers could not be found please check for errors"	This error occurs when the configuration levers contain any lever that does not exist or misspelled. For example if configuration contains "ScoreGroup-PhotoAAuthenticity": 1 .This error is returned when all the documents have been sent in the POST and the obverse has failed.
DocumentAnalysisError	"Error analyzing document"	Error analyzing document
EmptyDocumentError	"Empty document file"	The document file uploaded is empty.
InvalidImageType	"Invalid image type"	The image type is not correct
ImageAlreadyAnalyzedError	"The provided image type has already been uploaded and analyzed"	This error occurs when a process of an image type already exists. For example, if an image with reverse configuration is sent twice.
ErrorProcessingFile	"The file couldn't be processed properly"	This error occurs when the document file that is sent cannot be processed correctly, and therefore, Veridas cannot analyze it.
DocumentServiceNotReachable	Service url not set	Veridas Internal connectivity error
DocumentNfcUnavailableError	"Document Analysis error: NFC is not available for this document type"	This error occurs when a document type does not contain NFC. For example if you send NFC configuration for a document type ES_ResidencePermit_2010. The error is generic and occurs when using the "PUT document".
	"Obverse Document Analysis error: NFC is not available for this document type"	This error occurs when a document type does not contain NFC. For example, if you send NFC configuration for a document type ES_ResidencePermit_2010. This error is returned when all the documents have been sent in the POST, and the obverse has failed.
BlurredImageError	"Document Analysis error: The provided image does not meet the minimum quality"	This error occurs when image quality is bad and blurr of image is high. The error is generic and occurs when using the "PUT document".
	"Obverse Document Analysis error: The provided image does not meet the minimum quality"	This error occurs when Obverse quality is bad and blurr of image is high. This error is returned when all the documents have been sent in the POST, and the obverse has failed.
	"Reverse Document Analysis error: The provided image does not meet the minimum quality"	This error occurs when Reverse quality is bad and blurr of image is high. This error is returned when all the documents have been sent in the POST, and the reverse has failed.
AdditionalDocumentProcessError	"Main document not analyzed"	This error is related to "multiple onboarding". The main document has not been analyzed.
	"Previous additional document not uploaded"	This error is related to "multiple onboarding". The previous additional document has not be uploaded
	"You have already processed 3 additional documents"	This error is related to "multiple onboarding". 3 documents has already been processed.
	"The process for this additional document has already finished"	This error is related to "multiple onboarding". The process for an additional document has already finished
	"Obverse has not been uploaded for this additional document"	This error is related to "multiple onboarding". Obverse has not been uploaded for an additional document.
DocumentAnalyzingError	"Document Analysis error: The provided image has given an error while analyzing"	This error occurs when main process of document analysis has stopped. This is cause by different types of processing errors. The error is generic and occurs when using the "PUT document".
	"Obverse Document Analysis error: The provided image has given an error while analyzing"	This error occurs when main process of document analysis has stopped. This is cause by different types of processing errors. This error is returned when all the documents have been sent in the POST, and the obverse has failed.
	"Reverse Document Analysis error: The provided image has given an error while analyzing"	This error occurs when main process of document analysis has stopped. This is cause by different types of processing errors. This error is returned when all the documents have been sent in the POST, and the reverse has failed.

For example, when XpressID processes an image that does not correspond to the document type.

{
    type: "error",
    code: "ProcessError",
    message: "Error in the process",
    additionalData: "document",
    errorData: {
        errorCode: "UnknownDocumentTypeError",
        errorDetail: "Document Analysis error: The provided image could not be classified. Please verify that the image and the document type are correct."
        flow: "document"
        statusCode: 400
    }
}

Conection Error

This error occurs when any service fails. The structure of the received data is:

{
    type: "error",
    code: "ProcessError",
    message: "Error in the process.",
    additionalData: "connection".
}

Recommendations

This section includes general recommendations that ease integration with XpressID.

How to redirect onboardings from desktop to mobile using QR redirection

This recommendation aims to explain how to include a typical QR redirection process into an XpressID integration.

As explained in QR setup section, XpressID provides some configuration parameters that enable a QR redirection process to allow desktop users to continue an onboarding process from a mobile device, thereby increasing the quality of capturing process. However, an extra application backend logic is needed in order to enable this feature.

Next, required steps will be explained so integrators can add this logic to its backend.

Seting QR configuration parameters

When application backend makes an authentication request to XpressID authentication API (as explained in Architecture Overview integration section), it sends data configuration along with client_id and client_secret. In addition to other required parameters (depending on customer needs), mobileQrRedirect and mobileQrParams parameters must be sent, specifying the URL where QR users will be redirected to and optional parameters that will be added to the URL as query string parameters.

For this explanation, following values will be configured.

    {
        "mobileQrRedirect": "https://{APPLICATION_BACKEND_SERVER}",
        "mobileQrParams": {
            "user_id": "{USER_ID}"
        }
    }

• APPLICATION_BACKEND_SERVER: URL of application backend server where web requests will be served. This can be the same as the one serving authentication requests or a different one.
• USER_ID: Identifier of the user who has made the request to XpressID backend. This identifier needs to be created previously and will be related to the access token obtained through this call.

Once a valid access token is obtained, application backend logic must associate this access token to USER_ID so following requests (via QR redirection) made with query string ?user_id=USER_ID can be related to its corresponding access token. This process is freely managed by integrators but we strongly recommend to use any kind of database management.

Finally, application backend logic will use this access token to serve XpressID to frontend so users can start an onboarding as explained in Iframe integration section.

Adding a QR web server to backend

Once XpressID iframe is embedded into a web page, if it was configured with QR redirection as shown in previous step, it will initially show a QR asking user to continue process on a mobile or a desktop device. QR related URL will be: https://{APPLICATION_BACKEND_SERVER}/?user_id={USER_ID}.

When a user captures this QR it will be redirected to application backend server URL set before in mobileQrRedirect parameter. Therefore, this request must also be handled by application backend logic. This logic will retrieve USER_ID parameter from the request and will get its related access token afterwards. Note that this access token is the one obtained in previous call to XpressID authentication API.

Finally, application backend logic will use this access token to serve XpressID iframe to frontend for second time. However, this time onboarding will be done from a mobile device so QR won't be shown and user can start an onboarding normally.

Note that XpressID will automatically distinguish between mobile and desktop devices so previously configured mobileQrRedirect and mobileQrParams parameters won't take any effect and will be ignored.