VIX Verify greenID v4.2

This package provides capabilities that extend the Avoka Transact platform for users wishing to perform real-time identity verification of Australian individuals using the VIX Verify greenID service. A range of identity sources can be verified in either a background manner or an interactive verification process.

Background sources are run during the initial registration call to greenID. The individual has no opportunity to change their data to match a particular source — whatever data they are registered with is what is used for the check. As data cannot be changed, match rates are not as high as when the source is used in interactive mode.

Interactive sources are presented to the individual on-screen, allowing them to change their data to match a particular source prior to initiating the check. As individuals have the ability to modify their details, success rates are higher in the interactive mode. The acceptable changes that can be made by the individual are controlled through the Controlled Changes configuration of greenID, with an option to disallow changes if required by your risk profile.

The service interfaces with the greenID v1 APIs to verify individual details on a range of identity sources. A typical usage scenarios involve multiple calls to greenID 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 prior to the identity verification step and so will not need to be captured again. When verifying identity documents the individual is often given the option to enter a different name to accommodate scenarios where their name is different on the identity document.
    Note: greenID requires addresses to be provided in long format with street number, street name and street type broken out into separate data elements (see below for address fields required).
  2. Registration
    Having already captured personal details, we can perform an initial check based on this information which will initialise the greenID session (providing a verify user Id) and run any background sources. 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 greenID.
    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 greenID 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. Often a Driver's Licence will be sufficient to complete the verification and in some scenarios Driver's Licence information is also captured prior to the identity verification step and can be used in the Open Session operation.
    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.

Note: If a data source returns with "Not Contributing" state, it will be removed from available data source, the user needs to select another data source to verify.

Process Flow

Below is the process flow diagram for GreenID identity verification

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. 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 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.

greenID Verification Rules

Clients wishing to use the greenID service will be required to work with the greenID team to complete a Rules Checklist which will include defining preferences for rule sets, lock-out rules, background and interactive sources, enablement of watch lists and any other additional modules.

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

Supported Verification Sources

The following identity sources are supported:

  • Australian Driver's Licence
    Supporting all 8 States of Australia, individuals are required to select their State and enter their Driver's Licence Number. Only DVS Driver's Licence sources are supported.
  • Medicare Card
    Only the DVS Medicare source is supported.
  • Australian Passport
    Only the DVS Passport source is supported.
  • ASIC Personal Name Search
    This file contains the details of all individuals who are currently, or have been, directors of an ASIC registered company or other ASIC registered entity. This is a non-document source that is typically verified as a background check.
  • Australian Tenancy File
    This file contains the details of Australian tenants living in rental properties. All applications undertake a 100 point ID assessment to verify their identity. This is a non-document source that is typically verified as a background source.
  • Australian Electoral Roll
    All persons currently registered to vote will appear on the electoral roll. This is a non-document source that is typically verified as a background source.
  • Dun and Bradstreet (D&B) Credit File Header Data
    Compiled and maintained by D&B as part of their Consumer Credit Reporting Agency activities. Number of records disclosed by FCS Online (a D&B entity): over 16 million. Special conditions apply to the use of this data source (see Legal Considerations). This is a non-document source that is typically verified as a background source.
  • Birth Certificate
    A DVS source available to government agencies only.
  • Change of Name Certificate
    Also known as DVS Change of Name Certificate (BDM) or Change of Name Certificate (DVS).
  • Marriage Certificate
    Also known as DVS Marriage Certificate (BDM) or Marriage Certificate (DVS).

This list represents a subset of the available greenID data sources.

Usage Instructions

Use the following proceedure to configure GreenID in your form:

  • Add the GreenID Verify component onto your page or GreenID Dialog into the Dialogs folder of your form. If using the GreenID 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 GreenID Verify component (if using the dialog you will find this inside the Dialog Content block) and on the Properties tab select the Options, Background Sources, and 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 Failure 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 GreenID 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 GreenID 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 Background Checks

Typically you would trigger the GreenID background checks before the applicant is presented with the identity verification section of the form. This way, if the applicant is verified successfully on the background 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 background checks automatically at an appropriate time:

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

Dialog Usage Patterns

Avoka's recommended usage pattern is to trigger the background 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 GreenID
  data.greenidSelectSource = "";
  data.verifySources = "";
  Form.fireRule("click" ,"greenIdVerifyButton" , 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 GreenID Verify component as follows:

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

Address Format Requirement

GreenID requires a physical address provided in Long format with an explicit breakdown of address components as follows:

FieldDescription
Subdwelling The subdwelling value will contain floor/level identifiers and/or 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 expanded form (e.g. Australia).

Tamper Proofing

To help combat fraudulent applications this package includes a 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 Tamper Check groovy service, passing in key personal 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).

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

Note: Tamper Check Groovy service doesn't work with fluent functions because submit processing functions are not supported.

Licencing

Clients must ensure they are appropriately licences in order to use this package. Prior to using this package clients must establish a commercial arrangement directly with VIX Verify.

Compatibility

This package has the following compatibility requirements:

ModuleCompatibilityNotes
Transact Manager5.1.4 or above
Transact Maestro5.1.0 or above
greenID API VersionV1V2 and V3 not currently supported

Release Notes

Version 4.2June 13, 2023

  • Updated readme.html to Temenos branding.

Version 4.1November 16, 2022

  • Added additional fields for AEC - Date of Birth and Property Name.
  • Added additional help images for Change of Name Certificate and Marriage Certificate.
  • Added additional help images for drivers licenses.
  • Fixed AEC field creation that was using wp instead of aec.
  • Fixed Birth Certificate Registration State field showing only 5 states.
  • Fixed Birth Certificate Registration State field showing only 5 states.
  • Updated spelling to 'licence'.

Version 4.0July 25, 2022

  • Added two new source documents - Change of Name Certificate and Marriage Certificate.

Version 3.0Feb 28, 2022

  • Enhanced to add new "Card Number" field for DVS Driver's Licence checks, dependent on the user's state
Version 2.0
  • Enhanced to allow the choice of birth certificate as an option to improve quality of identity verification
  • Defect fix - remove mandatory check on Address Street Type field
Version 1.9
  • Defect fix - Citizenship source is missing Acquisition Date field.
  • Removed white pages as interactive source because it's no longer supported.
  • Added local mandatory check on Medicare expiry year field.
  • Updated service connection endpoint in documentation.
Version 1.8
  • Enhanced to support the "Not contributing" source state from GreenID to avoid unnecessary verification requests calls.
  • Defect fix - send passport details as part of a background source check.
  • Added process flow diagram and fixed minor typos.
Version 1.7
  • Added support for Maestro language translation features.
  • Added missing rule template to GreenID Verify Component.
Version 1.6
  • Medicare Expiry Year dropdown is now dynamically filled with valid values based on the current date and the selected month (Ref TPD-5062).
Version 1.5
  • Resolved defect where Country of Issue for Visa documents was being truncated to a single character (Ref TPD-5000).
Version 1.4 Version 1.3 Version 1.2
  • Added support for multiple verification sessions in a single transaction by optionally specifying a Role Identifier on the GreenID Verify component in Maestro.
Version 1.1
  • Created version 2 of the VIX Verify GreenID - Identity Verification dynamic data service. This service now passes dob (Date of Birth) to Medicare verification.

Services

VIX Verify GreenID - Identity Verification v9
This service facilitates real-time identify verification for Australia using the VIX Verify greenID 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.1.4
greenID API Version 1

Service Parameters

Name Description Required Default
greenIdRuleId The ruleId to use in the greenID API calls (default: "default") Yes default
recordGreenIdResponse Controls whether or not to record the entire response payload from greenID 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
verifyUserId 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. medicaredvs,nswregodvs

Sources can be verified one at a time (interactive) or multiple at once.

Yes
backgroundSources A comma separated list of identity verification sources to run as background checks on the registration event. E.g. dnb,nswregodvs

If background checks are requested, the relevant input fields must be populated as required.

A full list of sources can be found here.

Yes
getFields A boolean value to indicate that the list of Source Fields is required. When specified, a verification is not performed, unless this is a completely new session, in which case a registration will occur first.

If requested, the relevant input fields must be populated as necessary for a registration.

No
Personal Details Inputs:
  • title
  • firstName
  • middleNames
  • lastName
  • dateOfBirth
  • email
  • 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.

Phone numbers are optional.

Yes
Address Inputs:
  • flatNumber
  • streetNumber
  • streetName
  • streetType
  • suburb
  • state
  • postcode
  • country
Address of the individual being identified.

Address breakdown by street number, name and type is required by this service. State is expected to be the short code (e.g. NSW, VIC, QLD). All fields required except flatNumber and streetType.

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

Address breakdown by street number, name and type is required by this service. State is expected to be the short code (e.g. NSW, VIC, QLD). Previous address details optional.

No
Medicare Inputs:
  • medicaredvsCardColour *
  • medicaredvsNumber
  • medicaredvsNameOnCard
  • medicaredvsNameLine2
  • medicaredvsNameLine3
  • medicaredvsNameLine4
  • medicaredvsReferenceNumber
  • medicaredvsExpiryMonth
  • medicaredvsExpiryYear
  • medicaredvsExpiryDate
Medicare details to be verified against the medicaredvs source.

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

Name on Card is optional - if not provided the personal details will be used to construct this.

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

Expiry month must be provided as a number (e.g. February = 02)

For Yellow and Blue cards, expiry date can be provided as a single date field in Avoka standard date format yyyy-MM-dd.

Card colour must be Green, Yellow or Blue, or G, Y or B.

No
Licence Inputs:
  • regodvsState
  • regodvsNumber
  • regodvsFirstName
  • regodvsMiddleNames
  • regodvsLastName
Licence details to be verified against the regodvs sources.

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

No
Passport Inputs:
  • passportdvsNumber
  • passportdvsFirstName
  • passportdvsMiddleNames
  • passportdvsLastName
  • passportdvsGender
Passport details to be verified against the passportdvs source.

Gender can be provided as Male/Female or M/F.

No
Visa Inputs:
  • visadvsPassportNumber
  • visadvsFirstName
  • visadvsMiddleNames
  • visadvsLastName
  • visadvsPassportCountryOfIssue
Visa details to be verified against the visadvs source.

Country of issue must be the 3 letter country code of the country that issued the passport.

No
Birth Certificate Inputs:
  • birthdvsRegistrationNumber
  • birthdvsFirstName
  • birthdvsMiddleNames
  • birthdvsLastName
  • birthdvsRegistrationState
  • birthdvsRegistrationDate
  • birthdvsRegistrationYear
  • birthdvsCertificateNumber
  • birthdvsCertificatePrintedDate
Birth Certificate details to be verified against the birthcertificatedvs source.

Birth Certificate source only supports the following states NSW, QLD, SA, TAS, and VIC.

BirthdvsMiddleNames is optional.

birthdvsRegistrationDate is required for QLD and TAS States.

birthdvsRegistrationYear is required for NSW, VIC, QLDand (if the date of registration is on or after 2/7/1996), and TAS (if the date of registration is on or after 1/11/1999).

birthdvsCertificateNumber is required for SA (only for certificates issued after 1/11/1999).

birthdvsCertificatePrintedDate is required for SA.

All other fields required.

No
Citizenship Certificate Inputs:
  • citizenshipdvsStockNumber
  • citizenshipdvsAcquisitionDate
  • citizenshipdvsFirstName
  • citizenshipdvsMiddleNames
  • citizenshipdvsLastName
Immicard details to be verified against the citizenshipcertificatedvs source.

No
Immicard Inputs:
  • immicarddvsNumber
  • immicarddvsFirstName
  • immicarddvsMiddleNames
  • immicarddvsLastName
Immicard details to be verified against the immicarddvs source.

No
White Pages Inputs:
  • wpPhoneNumber
  • wpFirstName
  • wpLastName
  • wpFlatNumber
  • wpStreetNumber
  • wpStreetName
  • wpStreetType
  • wpSuburb
  • wpState
  • wpPostcode
White Pages details to be verified against the wp source.

No
Australian Electoral Roll Inputs:
  • aecFirstName
  • aecLastName
  • aecFlatNumber
  • aecStreetNumber
  • aecStreetName
  • aecStreetType
  • aecPropertyName
  • aecSuburb
  • aecState
  • aecPostcode
Australian Electoral Roll details to be verified against the aec source.

No
Change of Name Certificate Inputs:
  • changeofnamecertificatedvsGivenName
  • changeofnamecertificatedvsMiddleNames
  • changeofnamecertificatedvsSurname
  • changeofnamecertificatedvsOldFirstName
  • changeofnamecertificatedvsOldMiddleName
  • changeofnamecertificatedvsOldSurname
  • changeofnamecertificatedvsDob
  • changeofnamecertificatedvsRegistrationNumber
  • changeofnamecertificatedvsRegistrationDate
  • changeofnamecertificatedvsRegistrationYear
  • changeofnamecertificatedvsRegistrationState
  • changeofnamecertificatedvsCertificateNumber
  • changeofnamecertificatedvsCertificateIssuedDate
Change of Name Certificate details to be verified against the changeofnamecertificatedvs source.

changeofnamecertificatedvsOldGivenName is optional for NSW, QLD, VIC and WA.

changeofnamecertificatedvsOldMiddleName is optional.

changeofnamecertificatedvsOldSurname is optional for NSW, QLD, VIC and WA.

changeofnamecertificatedvsRegistrationDate is not required for QLD and TAS States.

changeofnamecertificatedvsRegistrationYear is required for NSW, VIC, WAand WA (if the date of registration is on or after 1/11/1999)

changeofnamecertificatedvsCertificateNumber is required for NT, NSW (for certificates issued after 1/7/2010), SA (for certificates issued after 1/11/1999), and ACT (for certificates issued on or after 1/5/2002).

changeofnamecertificatedvsCertificateIssuedDate is required based on same rules as for changeofnamecertificatedvsCertificateNumber.

All other fields required.

No
Marriage Certificate Inputs:
  • marriagecertificatedvsFirstName
  • marriagecertificatedvsMiddleName
  • marriagecertificatedvsSurname
  • marriagecertificatedvsSpouseFirstName
  • marriagecertificatedvsSpouseMiddleName
  • marriagecertificatedvsSpouseSurname
  • marriagecertificatedvsMarriageDate
  • marriagecertificatedvsRegistrationNumber
  • marriagecertificatedvsRegistrationYear
  • marriagecertificatedvsRegistrationState
  • marriagecertificatedvsCertificateNumber
  • marriagecertificatedvsCertificateIssuedDate
  • marriagecertificatedvsParty
Marriage Certificate details to be verified against the marriagecertificatedvs source.

marriagecertificatedvsRegistrationNumber is required except for TAS certificates issued after 1/11/2000.

marriagecertificatedvsRegistrationYear is required for NSW, VIC, WA and TAS.

marriagecertificatedvsCertificateNumber is required for ACT (for certificates issued after 1/5/2002), SA and NT.

marriagecertificatedvsCertificateIssuedDate is required in conjunction with marriagecertificatedvsCertificateNumber so same rules apply.

All other fields required.

No

Outputs

Name Description
verifyUserId 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 ]
availableSources The list of sources that should be presented to the user if they are given the opportunity to provide more information. This information is useful in an interactive use case.

The list will get smaller as the identity sources are processed as it will exclude:

  • sources that have already been verified
  • sources that will not help to verify the individual
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.
watchlistsFoundOn A comma separated list of watchlists that the individual was found on where the values could include DFAT, PEP, OFAC. This information is only provided if watchlists are enabled in the greenID account configuration.
creditHistoryResult If the DNB Credit Header check is enabled for background verification, this value will provide the greenID result value for this check. The value will be either VERIFIED or AUTOFAIL per the response from greenID.
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.
VIX Verify GreenID - Tamper Check v1
This service checks the supplied identity data against the previously stored identity data to ensure it has not been tampered with since the ID verification was completed.

Compatibility

Module Compatibility
Manager 5.0

Inputs

Name Description Required
trackingCode The transaction tracking code in which the ID check was performed. 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
Personal Details Inputs:
  • firstName
  • middleNames
  • lastName
  • dateOfBirth
Personal details of the individual.

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

Yes
Address Inputs:
  • streetNumber
  • streetName
  • streetType
  • suburb
  • state
  • postcode
  • country
Address of the individual being identified.

Address breakdown by street number, name and type is required by this service. State is expected to be the short code (e.g. NSW, VIC, QLD).

Yes

Outputs

Name Description
boolean true if the check was successful and the supplied data exactly matched the original identity information; false otherwise.

Service Connections

The following service connections are used by this package.

VIX Verify greenID
Property Name Description Required
Type HTTP Endpoint Yes
Endpoint Must point to the greenID endpoint
  • Test: https://test-au.vixverify.com/Registrations-Registrations/DynamicFormsService
  • Prod: https://au.vixverify.com/Registrations-Registrations/DynamicFormsService
Yes
Username The client username credential for the greenID service Yes
Password The client password credential for the greenID service Yes