Equifax IDMatrix v1.7

This package provides capabilities that extend the Avoka Transact platform for users wishing to perform real-time identity verification of Australian individuals using the Equifax IDMatrix service. A range of identity sources can be verified in an interactive verification process.

The service interfaces with the IDMatrix v4.0.12 APIs to verify individual details on a range of identity sources. A typical usage scenarios involve multiple calls to IDMatrix supporting an interactive data capture experience:

  1. Capture Personal Details
    The individual's full name, date of birth, contact details and residential address are usually captured as part of the input parameters sending to IDMatrix. In the meantime, user can also provide a document info each time to verify. But it's optional for the initial verification.

    Note: IDMatrix requires addresses to be provided either in long format with property name, unit number, street number, street name and street type broken out into separate data elements (see below for address fields required) or a single line format.

  2. Registration
    Having already captured personal details and optionally a document info, we can perform an initial check based on these information which will initialise the IDMatrix session (providing an enquiry Id). This action is commonly triggered when the user navigates to the identity verification page of the form.
    Under some scenarios with relaxed rules, this initial operation to open the session will result in a VERIFIED response from IDMatrix.
    From a form design perspective, this could be triggered by adding a Page change rule on the Page Controller (Content Container) and triggering the Verify Button click function.
    It is good practice to trigger this function each time the user returns to the identity verification page because if they have returned to earlier pages and modified their personal details, this call will re-initialise their IDMatrix session and ask them to restart their identity verification.
  3. Interactive Verification
    Usually the individual will be required to provide one or more document sources. The capture of additional document sources is interactive such that the individual need only provide one document source at a time. Each document source is verified in turn until a VERIFIED response is achieved or the individual cannot complete the verification.
    From a form design perspective, if the individual is unable to achieve a VERIFIED response, the option to upload scanned copied of their documents may be presented.

Process Flow

Below is the process flow diagram for Equifax IDMatrix service

Licensing

Clients must ensure they are appropriately licenses in order to use this package. Organisations who wish to use this package are required to establish a commercial relationship with Equifax IDMatrix directly.

Compatibility

This package has the following compatibility requirements:

ModuleCompatibilityNotes
Transact Manager5.0.4 or above
Transact Maestro5.0.14 or above
Equifax IDMatrix API Versionv4.0.12

Installation Instructions

To install this package please walk through the following proceedure:

  1. Unzip the package to a directory on your computer
  2. Import each zip archive found in the services folder to Transact Manager under the Services >> All Services menu item.
  3. Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
  4. Configure any required Service Connections. These requirements can be found at the bottom of this document or in the Help Doc for each of the imported services.

    Service Connections can be configured in Transact Manager under the Services >> Service Connections menu item.

  5. Import each archive found in the libraries folder to Maestro.

    Importing these into the Organisation level libraries folder is recommended as this will make the components available to all projects, however they can be imported at the Project level if required.

IdMatrix Verification Rules

Clients wishing to use the IDMatrix service will be required to work with the IDMatrix team to complete a Rules Checklist which will include defining appropriate values for configuration name, client cost centre, IDMatrix service name(s), interactive sources and any other additional modules.

The API integration is set to use the default values but this can be changed in the service parameters of the Equifax IDMatrix - Identity Verification dynamic data service.

Supported Verification Sources

The following identity sources are supported:

  • Australian Driver's License
    Supporting all 8 States of Australia, individuals are required to select their State and enter their Driver's License Number.
  • Medicare Card
  • Passport
  • Immigration Card
  • Citizenship Certificate
  • Birth Certificate
  • Change Of Name Certificate
  • Marriage Certificate

Usage Instructions

Use the following proceedure to configure IDMatrix in your form:

  • Add the Equifax IDMatrix Verify component onto your page or Equifax IDMatrix Dialog into the Dialogs folder of your form. If using the Equifax IDMatrix Verify component you may find it better to add it to a section configured with Top To Bottom Layout (in the Additional Layout properties) to provide more horizontal space.
  • Select the Equifax IDMatrix Verify component (if using the dialog you will find this inside the Dialog Content block) and on the Properties tab select the Options, Interactive Sources you wish to support.
  • Open the Input Fields section on the Properties tab and map all required fields into the input data maps.
  • In the Rules section, add any processing rules to handle On Verified and On Unverify events.

Help Display Option

This package provides an option to display help content during the interactive verification process. This help content includes document sample images indicating location of required information and related instructions. By default, this help content will be presented but may be disabled by deselecting the relevant configuration option.

Manual Verification Option

This package provides support for manual verfication should the user fail or opt out of the electronic verification. This feature can be enabled or disabled according to the usage requirements using the Allow Opt Out property on the Equifax IDMatrix Verify component.

Multiple Verification Sessions

If you need to perform id verifications on multiple individuals in a single transaction you will need to add an instance of the Equifax IDMatrix Verify component for each individual and specify a Role Identifier (found under Options on the Properties panel) for each instance. For example, if your form supports 2 applicants you would specify a Role Identifier of Applicant1 and Applicant2 respectively. This will ensure that the sessions do not interfere with each other.

Triggering the Checks

Typically you would trigger the IDMatrix checks before the applicant is presented with the identity verification section of the form. This way, if the applicant is verified successfully on the checks alone, then the identity verification section can be excluded from the applicant experience.

You can add the following call to a rule in your form to trigger the checks automatically at an appropriate time:

Form.fireRule("click" ,"idMatrixVerifyButton" , data);
where idMatrixVerifyButton is the ID of the Verify button located in the Equifax IDMatrix Verify component in the Verify sub-block.

Dialog Usage Patterns

Avoka's recommended usage pattern is to trigger the verification process when the applicant clicks the Continue button and on a page where we have captured all personal details required to do so. For example, if you wanted to trigger this process when the applicant clicks the Continue button at the bottom of page 2 of the form you could add this script to the click rule:

if(Form.getCurrentPageNumber() !== 2 || data.verifyStatus === "VERIFIED"){
  // If the applicant is verified or we are not on page 2 then continue as normal
  Form.$Pages.move(true)
} else {
  // If we are on page 2 and we are not yet verified then reset and trigger IDMatrix
  data.idmatrixSelectedSource = "";
  data.verifySources = "";
  Form.fireRule("click" ,"idMatrixVerifyButton" , data);
}

Additionally, if we receive a successful validation result then we should automatically progress to the next page. We can achieve this by adding to the On Verified rule of the Equifax IDMatrix Verify component as follows:

Form.showDialog(""); // Default script
Form.$Pages.move(true); // Move on to the next page

Address Format Requirement

IDMatrix requires a physical address provided either in a single line unformatted address or in Long format with an explicit breakdown of address components as follows:

FieldDescription
Property Name The Property name.
Unit Number The unit/flat/shop/suite identifiers.
Street Number For physical addresses this value will contain the street number of the address which does not include the unit or flat number, but may be represented as a range (e.g. 267-277). For non-physical addresses this field will contain the PO Box, Locked Bag, or similar data.
Street Name Where practical, this field will contain the name of the street only, with street type being provided separately (see below).
Street Type The street type value may be provided as an expanded value (e.g. ROAD) or abbreviation (e.g. RD), depending on the lookup service response data.
Locality The locality information varies from country to country but will usually be either suburb or city.
State The State that the address resides in. For some countries (e.g. New Zealand) this may be blank.
Postal Code The regional postal code, also referred to as Zip Code (US) and Postcode.
Country The Country that the address is located within, in its ISO Alpha-3 code form (e.g. AUS).

Please note that IDMatrix will attempt to match fielded addresses exactly as they are input. Therefore if the fielded data is invalid, the match rates on the data sources will be impacted. If you cannot provide a clean, structured address, please provide a single address string in the unformatted address field.

HTTP Audit Logging

For audit purposes the package provides a HTTP Audit feature that records information about each HTTP request call made in the execution of a service. If this feature is enabled at the service level, HTTP request and response information will be logged to a submission property on the transaction for which the request was made. The name of this submission property can be customized to suit your needs.

The audit information will be stored in the submission property as a JSON array with a structure as follows:

[
    {
        "serviceName": "EquifaxIDMatrix",
        "executionTimestamp": "2017-08-16 17:43:58 AEST",
        "durationMillis": 147,
        "request": {
            // Request Details
        }
        "reseponse": {
            // Response Details
        }
    },
    {
        "serviceName": "EquifaxIDMatrix",
        // Etc...
    }
]

See the documentation for the Identity Verification service for information on how to enable this feature.

Tamper Proofing

To help combat fraudulent applications this package includes Equifax IDMatrix - Tamper Check Groovy service that checks for data tampering to ensure that the data provided at submission time exactly matches the data used to complete the identity verification. To enable this capability you must add a call to the Equifax IDMatrix - Tamper Check groovy service, passing in key identity information attributes at the time of submission. If all provided data exactly matches the original identity this service will return a successful result (true), otherwise a failure will result (false).

Configuration

  1. Double check the identity data request parameters you want this service to check in Equifax IDMatrix - Identity Verification Service parameter: idMatrixTamperCheckRequestParams. For example, firstName,middleNames,lastName,dateOfBirth,streetNumber,streetName,streetType,suburb,state,postcode,country. The name must match the request parameter name that Equifax IDMatrix - Identity Verification service accepts.
  2. Write a Submission Completed Processor to call the Equifax IDMatrix - Tamper Check Groovy service to check the submission data. Below is an example on how to call the service.
    import com.avoka.core.groovy.GroovyLogger as logger
    import com.avoka.tm.svc.*
    import com.avoka.tm.vo.*
    import com.avoka.tm.util.Path
    import javax.servlet.http.*
    
    
    class FluentSubmissionCompletedProcessor {
    
    
        // change this value to match role defined in your form
        final static String ROLE_KEY = ''
        // change to your client code
        final static String CLIENT_CODE = 'exchange'
    
        /**
         * Perform submission completed processor service
         */
        void invoke(SvcDef svcDef, Txn txn, HttpServletRequest request, User user) {
    
            String verifyStatusTxnPropertyName = ROLE_KEY ? "EquifaxIDMatrix.${ROLE_KEY}.verifyStatus" : "EquifaxIDMatrix.verifyStatus"
            String verifyStatus = txn?.propertyMap?.get(verifyStatusTxnPropertyName)
    
            List identityData = []
            // get identity data and add to identityData list.
    
            if (verifyStatus) {
                // call Tamper Check to verify identity data not modified in any way
                // we don't give identityData on purpse cos we want to use xpath defined in form data extract
                Map params = [
                            "task": "check",
                            "roleKey": ROLE_KEY,
                            "identityData": identityData,
                            "txn": txn
                    ]
    
                    // calling tamper check groovy service
                    boolean success = new GroovyServiceInvoker()
                            .setServiceName('Equifax IDMatrix - Tamper Check')
                            .setClientCode(CLIENT_CODE)
                            .setVersionNumber(1)
                            .invoke(params)
    
                logger.info "Tamper Check result=$success"
                if (success==false) {
                    throw new Exception("Tamper Check failed. Identity data has been tampered!")
                }
            } else {
                logger.info "Identity data is not verified by IDMatrix service yet. Skip tamper check."
            }
    
    
        }
    }
    
  3. In "Form Version" - "Services" section in published form, select the "Submission Completed Processor" above.
  4. At runtime, Tamper check will be performed after form submitted. And result will be recorded as a submission property "EquifaxIDMatrix.roleName.identityDataTamperCheck" with possible values [passed | failed] to indicate the check result.

Note: you need to manually add this call to your post submit processing functions in order to utilise this feature.

Release Notes

Version 1.6Apr 27, 2022

  • Enhanced to add new "Card Number" field for DVS Driver's Licence checks
Version 1.5
  • Fixed validation bugs in medicare, birth certificate, and change of name services.
  • Fixed major validation bug (First name and Last name) in change of name certificate and validation messages order.
  • Fixed server error if applicant changes verification source service and sends partial params
  • Fixed multiple validation bugs in birth certificate and marriage certificate sources
  • Enhanced UX by auto-scrolling and setting focus upon selecting a service
  • Enhanced UX by creating consistency with Desktop view by enabling "Help images" in Mobile view

Version 1.4 Oct 16, 2017

  • Fixed birth certificate type cannot be disabled in Maestro component.

Version 1.3 Sep 26, 2017

  • Fixed middle name on card in medicare card verification blank value issue.

Version 1.2 Sep 7, 2017

  • Added support for tamper check.

Version 1.1 August 25, 2017

  • Added support for audit logging of all HTTP requests.

Version 1.0 August 8, 2017

  • Baseline release.

Services

Equifax IDMatrix - Identity Verification v5
This service facilitates real-time identify verification for Australia using the Equifax IDMatrix API. The service can be used to verify multiple document types (sources) in a single call or one at a time in a more interactive mode.

Service Connection

Compatibility

Module Compatibility
Manager 5.0.4
IDMatrix API Version 4.0.12

Service Parameters

Name Description Required Default
idMatrixConfigurationName To specify if you use more than 1 score card configuration. The actual values you need to use are defined during the product configuration process. If required, this value is provided by Equifax. No
idMatrixClientCostCentre to specify a cost centre the transaction should be charged to. If required, this value is provided by Equifax. No
idMatrixServiceNames Controls which set of component services are called during this request. Support multiple values separated by comma. No
idMatrixConsentEnums Consent Emum list separated by comma. Provide consent for searching against particular data sources. No AEC-ER,MIRUS-HER,BDMBC,BDMMC,BDMCON,CITIZEN-DOC,DIAC-RBD,VEDA-CBCOMM,VEDA-CBCONS,VEDA-CBPR,DL,ACC-PEPS,ACC-COMPLINK,IMMICARD-DOC,MEDICARE-CARD,VEDA-NTD,DFAT-AP,DIAC-VEVO,POAC,MIRUS-SPD,VEDA-PND,VEDA-EVVELOCITY,VEDA-SFD,IMG-DOC,SFA,PNV,DVI,KBA
idMatrixTamperCheckRequestParams Request parameter names separated by comma that should not be changed once verified. No firstName,middleNames,lastName,dateOfBirth,streetNumber,streetName,streetType,suburb,state,postcode,country
enableHttpAudit With HTTP auditing enabled, details about each HTTP request (including request and response data) are stored in a submission property as a JSON array against the relevant transaction. No false
httpAuditPropertyName Specify the name of the HTTP audit submission property to receive the audit information. No httpAudit
recordIDMatrixResponse Controls whether or not to record the entire response payload from IDMatrix as a submission property, useful if there is a requirement for the downstream system to receive this information. No false

Inputs

Name Description Required
roleKey Optionally provide a role key to support multiple identity sessions in a single transaction. A typical example would be Applicant 1 and Applicant 2. No
enquiryId The user ID is used in interactive mode to tie multiple calls together. This value is returned in the service response and must be passed in subsequent requests to maintain session integrity. No
verifySources A comma separated list of identity verification sources. E.g. drivers-licence-details,medicare

Sources can be verified one at a time (interactive) or multiple at once. Please note this flag is not a filter. The service will still send document info from client as much as possible even it's not in verifySources. However, if any of the document type from this list is verified from backend, service will set "sourceVerifiedFlag" to true in result JSON to indicate this specific document type verification is passed.

No
Personal Details Inputs:
  • title
  • firstName
  • middleNames
  • lastName
  • dateOfBirth
  • gender
  • email
  • alternativeEmail
  • homePhone
  • workPhone
  • mobilePhone
Personal details of the individual being identified.

Date of birth is expected to be received in Avoka standard format (yyyy-MM-dd) E.g. 2016-07-21.

Gender is expected to be received from Avoka gender field format (M/F) and it will be converted to IDMatrix format male/female Phone numbers are optional.

No
Current Address Inputs:
  • property
  • flatNumber
  • streetNumber
  • streetName
  • streetType
  • suburb
  • state
  • postcode
  • country
  • unformattedAddress
Address of the individual being identified.

State is expected to be the short code (e.g. NSW, VIC, QLD).

Country is expected to be the ISO Alpha-3 three letter code. For example: AUS. Valid country name is also acceptable and will be converted to ISO3 country code using standard Java Locale library but sending ISO3 code is preferred.

You can either fill unformattedAddress in one line format or the rest of the fields for structured address.

No
Previous Address Inputs:
  • previousProperty
  • previousFlatNumber
  • previousStreetNumber
  • previousStreetName
  • previousStreetType
  • previousSuburb
  • previousState
  • previousPostcode
  • previousCountry
  • previousUnformattedAddress
Previous address of the individual being identified.

State is expected to be the short code (e.g. NSW, VIC, QLD).

Country is expected to be the ISO Alpha-3 three letter code. For example: AUS. Valid country name is also acceptable and will be converted to ISO3 country code using standard Java Locale library but sending ISO3 code is preferred.

You can either fill unformattedAddress in one line format or the rest of the fields for structured address.

No
License Inputs:
  • regodvsState
  • regodvsNumber
  • regodvsCardNumber
License details to be verified.

regodvsState is expected to be the short code (e.g. NSW, VIC, QLD).

No
Passport Inputs:
  • passportdvsNumber
  • passportdvsCountryCode
Passport details to be verified.

passportdvsCountryCode Country of Issue of the Passport. Should be provided as ISO Alpha-3 three letter code. For example: AUS. Valid country name is also acceptable and will be converted to ISO3 country code using standard Java Locale library but sending ISO3 code is preferred.

No
Immigration Card Inputs:
  • immicarddvsNumber
  • immicarddvsDOB
Immigration card details to be verified.

immicarddvsDOB Use this field only when a partial date of birth is on the document (i.e. yyyy or mm-yyyy). If provided, it will override the full date of birth field in Personal Details

No
Citizenship Certificate Inputs:
  • citizenshipdvsStockNumber
  • citizenshipdvsAcquisitionDate
  • citizenshipdvsDOB
  • citizenshipdvsPrimaryCountry
  • citizenshipdvsOtherCountry
Citizenship Certificate details to be verified.

Date of acquisition is expected to be received in Avoka standard format (yyyy-MM-dd) E.g. 2016-07-21. citizenshipdvsDOB Use this field only when a partial date of birth is on the document (i.e. yyyy or mm-yyyy).

citizenshipdvsPrimaryCountry and citizenshipdvsOtherCountry need be provided as ISO Alpha-3 three letter code. For example: AUS.

No
Medicare Inputs:
  • medicaredvsNumber
  • medicaredvsReferenceNumber
  • medicaredvsMidnameOnCard
  • medicaredvsExpiryDate
  • medicaredvsColour
Medicare details to be verified.

Medicare Card Number is expected to contain only 10 digits, the reference number is provided separately.

Reference Number is the number next to the name indicating the individuals position on the card.

Expiry date can be provided as a single date field in Avoka standard date format yyyy-MM-dd or yyyy-MM for Green card.

Card colour must be G for green, Y or B.

No
Birth Certificate Inputs:
  • birthdvsRegistrationNumber
  • birthdvsRegistrationState
  • birthdvsRegistrationDate
  • birthdvsFirstName
  • birthdvsOtherNames
  • birthdvsLastName
  • birthdvsCertificateNumber
  • birthdvsDateOfPrint
  • birthdvsRegistrationDistrict
Birth Certificate details to be verified.

birthdvsRegistrationNumber is required for QLD (if issued on or after 02/7/1996), TAS (if issued on or after 01/11/1999) and all other states. Format needs to be without slash or the year - E.g. 12345/1983 = 12345 birthdvsRegistrationDate is required for QLD and TAS States in full date format (yyyy-MM-dd)

birthdvsRegistrationDate is required for NSW, VIC, WA in year format (yyyy)

birthdvsCertificateNumber is required for ACT (if issued on or after 01/5/2002) , SA (if issued on or after 1/11/1999) and for NT (if issued on or after 12/7/1999); optional otherwise.

birthdvsDateOfPrint is required for ACT, NT and SA States; optional otherwise.

birthdvsRegistrationDistrict is only required for WA State.

All other fields are required.

No
Change Of Name Certificate Inputs:
  • changenamedvsRegistrationNumber
  • changenamedvsRegistrationState
  • changenamedvsRegistrationDate
  • changenamedvsFirstName
  • changenamedvsOtherNames
  • changenamedvsLastName
  • changenamedvsCertificateNumber
  • changenamedvsDateOfPrint
Change Of Name Certificate details to be verified.

Old Given Name and Family Name are required for ACT, NT, SA, TAS states.

changenamedvsRegistrationNumber is required for TAS state if registration date is on or after 01/11/1999, and all other states.

changenamedvsRegistrationDate is required for QLD and TAS States in full date format (yyyy-MM-dd)

changenamedvsRegistrationDate is required for NSW, VIC, WA in year format (yyyy)

changenamedvsCertificateNumber is required for ACT (if issued on or after 01/5/2002) , SA (if issued on or after 1/11/1999) and for NT; optional otherwise.

changenamedvsDateOfPrint is required for ACT, NTstates; and SA if issued on or after 1/11/1999; optional otherwise.

No
Marriage Certificate Inputs:
  • marriagedvsRegistrationNumber
  • marriagedvsRegistrationState
  • marriagedvsRegistrationYear
  • marriagedvsMarriageDate
  • marriagedvsBridesFirstName
  • marriagedvsBridesOtherNames
  • marriagedvsBridesLastName
  • marriagedvsGroomsFirstName
  • marriagedvsGroomsOtherNames
  • marriagedvsGroomsLastName
  • marriagedvsCertificateNumber
  • marriagedvsDateOfPrint
  • marriagedvsRegistrationDate
Marriage Certificate details to be verified.

marriagedvsRegistrationYear is required for NSW, TAS, VIC, WA states.

marriagedvsRegistrationDate is required for QLD state.

marriagedvsCertificateNumber is required for ACT (if issued on or after 01/5/2002) , SA (if issued on or after 1/11/1999) and for NT; optional otherwise.

marriagedvsDateOfPrint is required for SA state (if issued on or after 1/11/1999), ACT and NT; optional otherwise.

All other fields are required.

No

Outputs

Name Description
enquiryId The identifier for the user session that may be used for subsequent calls.
verifyStatus The status of the verification for this individual with possible values [ VERIFIED | UNVERIFIED | FAILED ]
verifiedSources A list of sources that the individual has been successfully verified on, provided as a comma separated list of source codes.
sourceVerifiedFlag Will contain true if one or more of the requested verifySources was verified as a result of this request; false or blank otherwise.
executionStatus The status of the service execution [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ].

Successful execution will be denoted by a SUCCESS value. DATA_ERROR will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. SYSTEM_ERROR indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.

errorMessage When a DATA_ERROR is experienced, this value may provide more detail on the nature of the error.
Equifax IDMatrix - Tamper Check v1
This service checks the supplied identity data against the previously stored data to ensure it has not been tampered with since the ID verification was completed. It provides two main functions. One is to generate a hashcode based on identity Data and stores it into current submission. This is typically called after a successful ID verification.
The other one is to check if the current identity Data has been tampered in any way. This is done by rehashing the current identity Data and compares it with the hashcode previous stored. This is typically called in a submission complete processor to check if identity Data in submission are the same as the identity Data that has been ID verified.

This service supports identity data check for multiple roles in a single session. For example, you could have identity check for a husband and a wife and have this service check both of them submission data not being tampered.

Compatibility

Module Compatibility
Manager 5.0.4

Inputs

Name Description Required
task Task to perform with possible values [ store | check ]

store: It generates a hash code based on identity Data provided and stores it into current submission as txn property.

check: It regenerate hash code with current identity Data and compare it with the hash code stored previously in submission.

Yes
roleKey Optionally provide a role key to support multiple identity sessions in a single transaction. A typical example would be Applicant 1 and Applicant 2. No
txn current Txn object Yes
identityData Identity Data (List) to be hashed and stored. (For store task) or to be checked. (For check task) Yes

Outputs

Name Description
boolean (For store task) return true if hash data has been stored successfully. false otherwise.

Service Connections

The following service connections are used by this package.

Equifax IDMatrix
Property Name Description Required
Type HTTP Endpoint Yes
Endpoint Must point to the Equifax IDMatrix endpoint
  • Test: https://ctaau.vedaxml.com/cta/sys2/idmatrix-v4
  • Prod: https://vedaxml.com/sys2/idmatrix-v4
Yes
Username The client username credential for the IDMatrix service Yes
Password The client password credential for the IDMatrix service Yes