Introduction

Socure provides Identity (IDV) and document verification (DV) services through various modules (fraud, kyc, email risk, address risk, phone risk, global watchlist, alert list, social, and document verification) using machine learning algorithms.

Socure provides the following capabilities and benefits:

1. Identity Verification (IDV)
2. Document Verification (DV)

Package features include:

1. Verification services
   1. You can use this package to verify applicants using IDV and DV services
2. Max attempt control
   1. Limit the number of calls an application can make to Socure platform.
3. Analytics Milestones and Segmentation
   1. This package includes Pre-built Milestones to assist you to evaluate the quality of the service.
   2. This package includes pre-built Segments for Document Verification to give you clear view of the overall result and % of passport vs driver license used in the verification.
4. Server and Client value objects
   1. This will help to use the results in an external service, for example, a enrollment application.
5. Detailed data and system errors
   1. This can be particularly useful as the service will block unnecessary calls if anything is missing or wrong.
   2. It will also provide detailed messaging to help fix the problem, either for the applicant in case of missing information, or the form builder in case of misconfiguration.
6. TAF + Maven support
7. Exchange regression suite - automating over 50 scenarios
   1. This helps us improve turn around time in case of defects fixes.
   2. It also helps us makes release new enhancements faster.

This package is built on the Exchange Framework (TIF). It is used to develop integrations in Journey Manager in a more efficient, standardized and scalable manner to reduce the ongoing costs for upgrades and maintenance.

Licensing

Clients must ensure they are appropriately licensed in order to use this package. Organisations who wish to use this package are required to establish a commercial relationship with the 3rd party vendor directly.

Compatibility

This package has the following compatibility requirements:

Release Notes

Version 1.0 Feb 28, 2020

• Baseline release.

Installation

Exchange Installation

This package should be installed as a single archive via the Temenos Marketplace. Once installed you should walk through the following procedure to ensure you complete any required configuration:

1. Review the documentation below for each of the imported services and make any adjustments necessary to service parameters.
2. Review the documentation below for any Service Connections and add your credentials as required.
3. Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
4. Review the Service Connection requirements under the same Help Doc tab for each of the imported services and make any required configurations to the Service Connection. Service Connections can be configured in Journey Manager under the Services >> Service Connections menu item.
5. Installation of any included Maestro libraries requires you to login to your Maestro server and import them either into your organization (for global availability) or to your specific project.

Note: The default value of service parameters from this package, such as maxAttemptNumber will always override the value for existing service. After you reinstall or upgrade the package, make sure the service parameters value are suitable to your requirement.

Maven dependency

Note: Each service within this package must have Unified App Data enabled when building a form. Navigate to Forms > Form > Form Version and tick the Unified App Data checkbox.

How to trigger fluent functions in Narrator

Below is the example on how to trigger the fluent functions and provide input parameters in Form Narrative

{
  "name": "Socure Narrative",
  "version": "1.0.0",
  "pages": [
    {
      "name": "ConfigurationPage",
      "allowGoBack": false,
      "allowSubmit": false,
      "condition": true,
      "preActions": [],
      "postActions": [],
      "nextPages": [
        "PrimaryApplicant",
        "MaxAttempt"
      ]
    },
    
    {
      "name": "PrimaryApplicant",
      "allowGoBack": true,
      "allowSubmit": false,
      "condition": "${ !txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft') || (txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft') && (txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft').toInteger() > 0) )}",
      "preActions": [],
      "postActions": [
        {
          "name": "Socure - IDV",
          "version": "1.0.0",
          "alwaysProcess": true,
          "params": {
            "Email": "${xmlPath.val('//Email')}",
            "FirstName": "${xmlPath.val('//FirstName')}",
            "SurName": "${xmlPath.val('//SurName')}",
            "Country": "${xmlPath.val('//Country')}",
            "PhysicalAddress": "${xmlPath.val('//PhysicalAddress')}",
            "City": "${xmlPath.val('//City')}",
            "State": "${xmlPath.val('//State')}",
            "Zip": "${xmlPath.val('//Zip')}",
            "MobileNumber": "${xmlPath.val('//MobileNumber')}",
            "IpAddress": "${xmlPath.val('//IpAddress')}",
            "NationalId": "${xmlPath.val('//NationalId')}",
            "Dob": "${xmlPath.val('//Dob')}",
            "ApplicantRole": "${xmlPath.val('//ApplicantRole')}",
            "debug":"${ !txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft') || (txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft') && (txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft') > 0) )}",
            "debug1":"${ !txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft') }",
            "debug2":"${ (txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft') && (txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft').toInteger()  > 0) )}",
            "debug2.1":"${ (txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft') && (txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft')  > 0) )}",
            "debug3":"${ (txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft')  )}",
            "debug4":"${ ( (txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft') > 0) )}"

          }
        }
      ],
      "nextPages": [
        "PrimaryApplicantSocure"
      ]
    },
    {
      "name": "PrimaryApplicantSocure",
      "allowGoBack": true,
      "allowSubmit": false,
      "condition": true,
      "preActions": [],
      "postActions": [],
      "nextPages": [
        "DeclineIDV",
        "MaxAttempt",
        "ResubmitAddressPrimaryApplicant",
        "DocumentVerificationPrimaryApplicant",
        "JoinApplicant",
        "ManualReview",
        "Accept"
      ]
    },
    {
      "name": "ResubmitAddressPrimaryApplicant",
      "allowGoBack": false,
      "allowSubmit": false,
      "condition": "${txn.propertyMap.get('Socure.IDV.Result.PrimaryApplicant.decisionValue')=='resubmit' }",
      "preActions": [],
      "postActions": [],
      "nextPages": [
        "PrimaryApplicant"
      ]
    },
    {
      "name": "DocumentVerificationPrimaryApplicant",
      "condition": "${txn.propertyMap.get('Socure.IDV.Result.PrimaryApplicant.decisionValue')=='refer' }",
      "allowGoBack": false,
      "allowSubmit": false,
      "preActions": [],
      "postActions": [],
      "formActions": [
        {
          "name": "Socure - Document Verification",
          "version": "1.0.0",
          "params": {
          }
        }
      ],
      "nextPages": [
        "DeclineDV",
        "JoinApplicant",
        "Accept"
      ]
    },
    {
      "name": "JoinApplicant",
      "allowGoBack": true,
      "allowSubmit": false,
      "condition": "${xmlPath.val('//IndividualOrJoinApplication') == 'Joint' && ( !txn.propertyMap.get('Socure.IDV.JointApplicant.currentAttemptsLeft') || ( txn.propertyMap.get('Socure.IDV.JointApplicant.currentAttemptsLeft') && (txn.propertyMap.get('Socure.IDV.JointApplicant.currentAttemptsLeft').toInteger() > 0)  ))}",
      "preActions": [],
      "postActions": [
        {
          "name": "Socure - IDV",
          "version": "1.0.0",
          "alwaysProcess": true,
          "params": {
            "Email": "${xmlPath.val('//Email_2')}",
            "FirstName": "${xmlPath.val('//FirstName_1')}",
            "SurName": "${xmlPath.val('//SurName_1')}",
            "Country": "${xmlPath.val('//Country_1')}",
            "PhysicalAddress": "${xmlPath.val('//PhysicalAddress_1')}",
            "City": "${xmlPath.val('//City_1')}",
            "State": "${xmlPath.val('//State_1')}",
            "Zip": "${xmlPath.val('//Zip_1')}",
            "MobileNumber": "${xmlPath.val('//MobileNumber_1')}",
            "IpAddress": "${xmlPath.val('//IpAddress_1')}",
            "NationalId": "${xmlPath.val('//NationalId_1')}",
            "Dob": "${xmlPath.val('//Dob_1')}",
            "ApplicantRole": "${xmlPath.val('//ApplicantRole_2')}",
            "debug1": "${jsonSlurper.parseText( txn.propertyMap.get('decision') ) && jsonSlurper.parseText( txn.propertyMap.get('decision') )['destinations']['resubmitWithResidentialAddressPrimaryApplicant']['isActive']}",
            "debug2":"${(jsonSlurper.parseText( txn.propertyMap.get('decision') ) && jsonSlurper.parseText( txn.propertyMap.get('decision') )['destinations']['referToDocumentVerificationPrimaryApplicant']['isActive'] && jsonSlurper.parseText( txn.propertyMap.get('decision') )['destinations']['referToDocumentVerificationPrimaryApplicant']['reasons'].findIndexOf('documentVerificationByKYCTwoPrimaryApplicant') >= 0   )}",

          }
        }
      ],
      "nextPages": [
        "JointApplicantSocure"
      ]
    },
    {
      "name": "JointApplicantSocure",
      "allowGoBack": true,
      "allowSubmit": false,
      "condition": true,
      "preActions": [],
      "postActions": [],
      "nextPages": [
        "DeclineIDV",
        "MaxAttempt",
        "ResubmitAddressJointApplicant",
        "DocumentVerificationJointApplicant",
        "ManualReview",
        "Accept"
      ]
    },{
      "name": "ResubmitAddressJointApplicant",
      "allowGoBack": false,
      "allowSubmit": false,
      "condition": "${txn.propertyMap.get('Socure.IDV.Result.JointApplicant.decisionValue')=='resubmit' }",
      "preActions": [],
      "postActions": [],
      "nextPages": [
        "JoinApplicant"
      ]
    },
    {
      "name": "DocumentVerificationJointApplicant",
      "condition": "${txn.propertyMap.get('Socure.IDV.Result.JointApplicant.decisionValue')=='refer' }",
      "allowGoBack": false,
      "allowSubmit": false,
      "preActions": [],
      "postActions": [],
      "formActions": [
        {
          "name": "Socure - Document Verification",
          "version": "1.0.0",
          "params": {
          }
        }
      ],
      "nextPages": [
        "DeclineDV",
        "ManualReview",
        "Accept"
      ]
    },
    {
      "name": "ManualReview",
      "allowGoBack": false,
      "allowSubmit": true,
      "condition": "${txn.propertyMap.get('Socure.IDV.Result.PrimaryApplicant.decisionValue')=='review' || txn.propertyMap.get('Socure.IDV.Result.JointApplicant.decisionValue')=='review' }",
      "preActions": [],
      "postActions": [],
      "nextPages": []
    },
    {
      "name": "MaxAttempt",
      "allowGoBack": false,
      "allowSubmit": true,
      "condition": "${ (txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft') && (txn.propertyMap.get('Socure.IDV.PrimaryApplicant.currentAttemptsLeft').toInteger() <= 0)) || (txn.propertyMap.get('Socure.IDV.JointApplicant.currentAttemptsLeft') && (txn.propertyMap.get('Socure.IDV.JointApplicant.currentAttemptsLeft').toInteger() <= 0)) }",
      "preActions": [],
      "postActions": [],
      "nextPages": []
    },
    {
      "name": "DeclineIDV",
      "allowGoBack": false,
      "allowSubmit": true,
      "condition": "${txn.propertyMap.get('Socure.IDV.Result.PrimaryApplicant.decisionValue')=='reject' || txn.propertyMap.get('Socure.IDV.Result.JointApplicant.decisionValue')=='reject'}",
      "preActions": [],
      "postActions": [],
      "nextPages": []
    },  {
      "name": "DeclineDV",
      "allowGoBack": false,
      "allowSubmit": true,
      "condition": "${( txn.propertyMap.get('Socure.DV.Result.PrimaryApplicant.decisionValue') !='accept' && txn.propertyMap.get('Socure.IDV.Result.PrimaryApplicant.decisionValue') == 'refer') || (txn.propertyMap.get('Socure.DV.Result.JointApplicant.decisionValue') !='accept' && txn.propertyMap.get('Socure.IDV.Result.JointApplicant.decisionValue') == 'refer' ) }",
      "preActions": [],
      "postActions": [],
      "nextPages": []
    },
    {
      "name": "Accept",
      "allowGoBack": false,
      "allowSubmit": true,
      "condition": true,
      "preActions": [],
      "postActions": [],
      "nextPages": []
    }
  ]
}

High Level Diagram

IDV

DV

Configuration

Socure Configuration

• Make sure to whitelist Journey Manager IP address before calling Socure API servers. Whitelisting can be done through Socure Admin console.

Maestro

Use the following procedure to configure the Socure Document Verification component in your form:

• Make sure the exchange-socure-taf Maestro library has been added to your project.
• From the Maestro palette, add the Socure Document Verification component onto your form.
• If you need to perform document verification on multiple individuals in a single transaction you will need to add an instance of the Socure Document Verification component for each individual and add applicant role identifier to the beginning of the component ID for each instance. For example, if your form supports 2 applicants you would specify a component ID of applicant1_socure_dV and applicant2_socure_dV respectively. This will ensure that the sessions do not interfere with each other.
• Once the form is published, make sure you enable the Unified App Data as follows:
  • Navigate to Forms>Form>Form Version and tick the Unified App Data checkbox.

Note: By default, the Maestro form will show an alert box when validation errors happen. Since the component already has the built-in fields to display various data errors, you can add the following Javascript on Form Load in your form to suppress the alert box.

    Form.serverValidationErrorHandler = function() {};

Max Attempt

This feature is intended to limit the number of calls to Socure ID+ API.

Configuration

1. Set the maxAttemptNumber to a positive number in the service parameter. The default value is 3.
2. If you don't want to apply any restriction, set it to -1. However, it is recommended to limit the number of calls.
3. If you want to alert the applicant to the number of attempts that are left, the number of attempts remaining display in both the JSON result and Data Field:attemptsLeft in the Maestro component.
4. If you want to alert the applicant to the number of attempts that are left, the number of attempts remaining display in both the JSON result and Data Field:attemptsLeft in the Maestro component.
5. If you want to define specific behaviour in the form, capture the SYSTEM_ERROR. errorCode: EXCEEDED_NUMBER_OF_ATTEMPTS that is sent back when the max attempt is exceeded.

Journey Analytics

Milestone events

Milestone events are automatically generated to show milestones on the User Journey view in Journey Analytics, the Journey platform analytics tool.

Segment events

Segment events are automatically generated to show segments on the User Journey view in Journey Analytics, the Journey platform analytics tool.

Service Txn properties/ Server VO

The table bellow describes IDV server VO fields stored in the Form XML Data and also stored in transaction properties.

The table bellow describes Document Verification server VO fields stored in the Form XML Data and also stored in transaction properties.

Configuration Service Support

Create a service parameter keyMapping as below in your configuration service (service-def.json) if you haven't done so

    {
      "name": "keyMapping",
      "type": "String",
      "filePath": "json/keyMapping.json",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    },

Note: You only need to create keyMapping service parameter once when you setup your first Exchange package. The rest of the Exchange packages will just keep adding content into the existing service parameter.

Create or append the following content into json/keyMapping.json

  "socure": [
    {
      "serviceKey": "idv",
      "serviceName": "Socure - IDV",
      "serviceParamKeyMap": {
        "recResInXml": "recordResponseInTxnXML",
        "recResInProp": "recordResponseInTxnProperties"
      }
    },
    {
      "serviceKey": "dv",
      "serviceName": "Socure - Document Verification",
      "serviceParamKeyMap": {
        "recResInXml": "recordResponseInTxnXML",
        "recResInProp": "recordResponseInTxnProperties"
      }
    }
  ]

Copy the following service parameters definition in your configuration service (service-def.json) and set the proper values for your project.

    {
      "name": "socure-idv|1.0.0-conn.endpoint",
      "description": "",
      "value": "",
      "type": "String",
      "bind": false,
      "required": true,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-idv|1.0.0-conn.password",
      "description": "",
      "value": "",
      "type": "Password",
      "bind": false,
      "required": true,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-idv|1.0.0-maxAttemptNumber",
      "description": "",
      "value": "-1",
      "type": "Number",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-idv|1.0.0-recResInProp",
      "description": "",
      "value": "false",
      "type": "Boolean",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-idv|1.0.0-recResInXml",
      "description": "",
      "value": "true",
      "type": "Boolean",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-idv|1.0.0-modules",
      "description": "",
      "value": "fraud,emailrisk,phonerisk,addressrisk,kyc,social,watchliststandard,alertlist,decision",
      "type": "String",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-idv|1.0.0-watchlistFilters",
      "description": "",
      "value": "",
      "type": "String",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-idv|1.0.0-forceRefresh",
      "description": "",
      "value": "false",
      "type": "Boolean",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-idv|1.0.0-moduleValidationRules",
      "description": "",
      "value": "{\n  \"modules\": {\n    \"fraud\": {\n      \"required\": [\n        \"FirstName\",\n        \"SurName\",\n        \"Country\"\n      ],\n      \"optionalRequired\": [\n        \"Email\",\n        \"MobileNumber\",\n        \"PhysicalAddress,City,State,Zip\"\n      ],\n      \"optimal\": [\n        \"PhysicalAddress2\",\n        \"IpAddress\",\n        \"NationalId\",\n        \"Dob\",\n        \"Email\",\n        \"MobileNumber\",\n        \"PhysicalAddress,City,State,Zip\"\n      ]\n    },\n    \"emailrisk\": {\n      \"required\": [\n        \"Email\"\n      ],\n      \"optionalRequired\": [],\n      \"optimal\": [\n        \"PhysicalAddress2\",\n        \"FirstName\",\n        \"SurName\",\n        \"Email\",\n        \"PhysicalAddress,City,State,Zip\",\n        \"Country\"\n      ]\n    },\n    \"phonerisk\": {\n      \"required\": [\n        \"MobileNumber\",\n        \"Country\",\n        \"FirstName\",\n        \"SurName\"\n      ],\n      \"optionalRequired\": [],\n      \"optimal\": [\n        \"PhysicalAddress2\",\n        \"PhysicalAddress,City,State,Zip\"\n\n      ]\n    },\n    \"addressrisk\": {\n      \"required\": [\n        \"FirstName\",\n        \"SurName\",\n        \"Country\",\n        \"PhysicalAddress,City,State,Zip\"\n      ],\n      \"optionalRequired\": [],\n      \"optimal\": [\n        \"PhysicalAddress2\",\n        \"IpAddress\",\n        \"MobileNumber\",\n        \"Email\"\n      ]\n    },\n    \"kyc\": {\n      \"required\": [\n        \"FirstName\",\n        \"SurName\",\n        \"Country\"\n      ],\n      \"optionalRequired\": [\n        \"NationalId\",\n        \"Dob\",\n        \"PhysicalAddress,City,State,Zip\"\n      ],\n      \"optimal\": [\n        \"PhysicalAddress2\",\n        \"NationalId\",\n        \"Dob\",\n        \"PhysicalAddress,City,State,Zip\"\n      ]\n    },\n    \"social\": {\n      \"required\": [],\n      \"optionalRequired\": [],\n      \"optimal\": [\n        \"PhysicalAddress2\",\n        \"FirstName\",\n        \"SurName\",\n        \"Email\",\n        \"MobileNumber\",\n        \"PhysicalAddress,City,State,Zip\"\n      ]\n    },\n    \"watchliststandard\": {\n      \"required\": [\n        \"FirstName\",\n        \"SurName\"\n      ],\n      \"optionalRequired\": [],\n      \"optimal\": [\n        \"Dob\"\n      ]\n    },\n    \"watchlistplus\": {\n      \"required\": [\n        \"FirstName\",\n        \"SurName\"\n      ],\n      \"optionalRequired\": [],\n      \"optimal\": [\n        \"Dob\"\n      ]\n    },\n    \"watchlistpremier\": {\n      \"required\": [\n        \"FirstName\",\n        \"SurName\"\n      ],\n      \"optionalRequired\": [],\n      \"optimal\": [\n        \"Dob\"\n      ]\n    },\n    \"alertlist\": {\n      \"required\": [],\n      \"optionalRequired\": [],\n      \"optimal\": [\n        \"FirstName\",\n        \"SurName\",\n        \"NationalId\",\n        \"Email\",\n        \"MobileNumber\",\n        \"IpAddress\"\n      ]\n    }\n  }\n}\n\n",
      "type": "String",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-idv|1.0.0-decision",
      "description": "",
      "value": "",
      "type": "String",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-idv|1.0.0-conn.endpoint",
      "description": "",
      "value": "",
      "type": "String",
      "bind": false,
      "required": true,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-idv|1.0.0-conn.password",
      "description": "",
      "value": "",
      "type": "Password",
      "bind": false,
      "required": true,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-dv|1.0.0-maxAttemptNumber",
      "description": "",
      "value": "-1",
      "type": "Number",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-dv|1.0.0-recResInProp",
      "description": "",
      "value": "false",
      "type": "Boolean",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-dv|1.0.0-recResInXml",
      "description": "",
      "value": "true",
      "type": "Boolean",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    },
    {
      "name": "socure-dv|1.0.0-sandboxUuid",
      "description": "",
      "value": "",
      "type": "String",
      "bind": false,
      "required": false,
      "clearOnExport": false,
      "readOnly": false
    }

Note: Once you setup your application to use configuration service, all the service connection and service parameters data directly comes from the your configuration service. So there is no need to setup the original service connection or service parameter of the Exchange fluent function.

Enable/Disable the configuration service

  ConfigServiceName=MyCompanyServiceConfiguration

Note: Configuration service is an organisation level option. Once enabled, all Exchange services within the organisation will start retrieving the service connection and service parameters info from configuration service you specified above.

Shared Styles

• Button Graphical Library: exchange-socure-taf

• License Icon Font Style Library: exchange-socure-taf

• Socure Choose File Library: exchange-socure-taf

• Socure Choose File Button Library: exchange-socure-taf

• Socure Document Verification Style Library: exchange-socure-taf

• socure-front-attachment Library: exchange-socure-taf