FIS ChexSystems v1.3
This package provides capabilities that extend the Avoka Transact platform for users wishing to:
- Perform real-time fraud checks during onboarding flows for US Checking Accounts using FIS QualiFile
- Perform real-time identity verification and OFAC check of US individuals using FIS ChexSystems Identity Verification and OFAC check service.
- Perform real-time identity verification of US individuals using FIS ChexSystems ID Authentication service (Also known as Knowledge Based Authentication / KBA).
- Perform regular checks against the FIS password expiry API and to either warn of imminent expiry or automatically refresh the password before expiry (default).
This package provides the following components
-
ChexSystems Verification - FIS
This component provides ability to call either ChexSystems QualiFile verification or Identity verification/OFAC check services.
-
ChexSystems IDA - FIS
This component provides real-time identity verification of US individuals using FIS ChexSystems ID Authentication service.
NOTE : Each component provides a single verification service that can be used together in any combination in any order to best suit FI needs. For example, a FI may choose to perform a IDV/OFAC verification first, and if IDV verification fails, perform another IDA verification to further verify the user. Other FI may choose always perform QualiFile verification first, and then IDV and then IDA. These can all be achieved easily during form design stage.
Installation Instructions
To install this package please walk through the following proceedure:
- Unzip the package to a directory on your computer
- Import each zip archive found in the services folder to Transact Manager under the Services >> All Services menu item.
- Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
- 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.
- 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.
Using ChexSystems Verification block
Drag a ChexSystems Verification block and place it on the form. In the "Input Data" section, first select "Validation Type" you want this block to perform. Then configure "FIS ChexSystems Input Fields" through field references. Once validation performed, it will save the result data into the data fields inside this components as follows:
- executionStatus
Execution Status.
- qualiFileStatus
QualiFile Validation Status.
- idvVerifyStatus
Identity Verification Status.
- idvNoRecordFound
No Record Found for IDV.
- ofacStatus
OFAC check Status.
NOTE : qualiFileStatus is only available when choosing QualiFile type. idvVerifyStatus and ofacStatus are available if you select IDV/OFAC type. Check FIS ChexSystems - IDV and FIS ChexSystems - QualiFile for possible values and explanation.
Using ChexSystems IDA block
Drag a ChexSystems IDA block and place it on the form. In the "Input Data" section, configure "ChexSystems IDA Input Fields" through field references. In the rendered form, after user entered personal information and clicked Verify button, it will show up a set of questions for the user to answer. When all questions being answered, clicking Verify button again will either bring two more challenge questions or come back with the final validation result. Once validation performed, it will save the result data into the data fields inside resultData block in the components as follows:
- executionStatus
Execution Status.
- verifyStatus
IDA Verification Status.
NOTE : verifyStatus is only available on final validation result. During questions/challenge questions stage, verifyStatus is blank. Check FIS ChexSystems - IDA for possible value and explanation.
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 FIS directly.
Compatibility
This package has the following compatibility requirements:
Module | Compatibility | Notes |
---|---|---|
Transact Manager | 5.0.2 or above | |
Transact Maestro | 5.0.25 or above | |
QualiFile Consumer API Version | N003 | |
IDA Product Version | 0001 | |
IDA Product Code | 01 | |
Service Authentication API Version | V002 |
Release Notes
Version 1.3 Aug 9, 2017
- Added support for multiple role verification in same session.
- Added max attempts control.
Version 1.2 Jun 22, 2017
- Added support for Maestro 5.1 language translation features.
- Display error message in case of data error or system error.
- Fixed a bug that service doesn't return data error message when mandatory field is empty.
Version 1.1 Mar 24, 2017
- Fixed compatibility issue with Groovy 2.4.8 in TM 5.1
Version 1.0 Feb 26, 2017
- Baseline release.
Maestro Assets
Provides real-time identity verification of US individuals using FIS ChexSystems ID Authentication service.
Service Calls
Rule Templates
You may add your own logic to handle the following rule types triggered by this component:
- On Verified : Gets executed when the identity verification is successful and complete
- On Verify Failed : Gets executed upon identity verification terminal failure where the individual could not complete the verification requirements
- On Data Error : Gets executed upon data error
- On System Error : Gets executed upon system error
Properties
Property | Category | Description | Type | Default |
---|---|---|---|---|
ChexSystems IDA Input Fields | Input Data | Defines input mappings for the person data collected elsewhere in the form.
Field Refs:
|
fieldRefMap | |
Applicant Role Name | Input Data | If you have multiple instance of this block, you need to give each one a unique role name here so that server can support multiple verification instance. | text |
Provides ability to call either ChexSystems QualiFile verification or Identity verification/OFAC check services.
Service Calls
Rule Templates
You may add your own logic to handle the following rule types triggered by this component:
- On IDV Verified : Gets executed when the IDV verification is successful and complete
- On IDV Verify Failed : Gets executed upon identity verification terminal failure where the individual could not complete the verification requirements
- On OFAC Passed : Gets executed when the OFAC check is passed
- On OFAC Failed : Gets executed when the OFAC check is failed
- On QualiFile Accept : Gets executed when the QualiFile verification is successful and complete
- On QualiFile Review : Gets executed when the QualiFile verification needs manually reviewed
- On QualiFile Decline : Gets executed upon QualiFile verification failed
- On Data Error : Gets executed upon data error
- On System Error : Gets executed upon system error
Properties
Property | Category | Description | Type | Default |
---|---|---|---|---|
FIS ChexSystems Input Fields | Input Data | Defines input mappings for the person data collected elsewhere in the form.
Field Refs:
|
fieldRefMap | |
Verification Type | Input Data | Validation type, Either choose ID Verification/OFAC or QualiFile. Default value is QualiFile Check.
Options:
|
option |
qualiFile
|
Applicant Role Name | Input Data | If you have multiple instance of this block, you need to give each one a unique role name here so that server can support multiple verification instance. | text |
Services
User Level Credential
By default, this service will send customerid and locationid values defined in service parameters. However it also supports send different customerid and locationid values for specific TM users. You can do this as follows:
- In TM, Click 'Forms' -> 'Property Types', Create two new Property Types as 'fisCustomerId' and 'fisLocationId', make them 'User' scope.
- Click 'Security' -> 'User Account', select a user, In 'User Profiles' tab, click the current profile, In 'User Properties' tab, set a new value for 'fisCustomerId' and 'fisLocationId'
- Once it's done, when this user login and use the FIS ChexSystems service, it will send this user's customerid and locationid instead of default customerid and locationid in service paramerters.
Prevent Multiple Verification Attempt
When service parameter "preventMultiAttempt" set to true, it will prevent following verification request if any
previous verification is FAILED
in the same submission. If this is the case, it will not call FIS
hexSystems IDA web service, instead, will return FAILED
response immediately. On TM server it will
also write txn property "FisIda.multipleVerifyAfterFail"="true" in current txn.
There is also another service parameter maxAttemptNumber when set to a positive number, it will control the maximum number an applicant can perform the FIS IDA service in the same transaction and returns DATA_ERROR when max attempt exceeded with errorCode: EXCEEDED_NUMBER_OF_ATTEMPTS. Its default value is -1 which means no restriction. If this parameter is set to positive number, it will also include The number of attempts left for calling this service in result JSON.
Service Connection
Compatibility
Module | Compatibility |
---|---|
Manager | 5.0.2 |
Service Parameters
Name | Description | Required | Default |
---|---|---|---|
fisCustomerId | Customer Identifier, assigned by Decision Solutions to identify the financial institution. | Yes |
10000000
|
fisStaging | Set to false if it's a production system, otherwise leave it to true for all testing environment. This will affect data sending to QualiFile service | Yes |
true
|
fisLocationId | Unique identifier of the person doing the inquiry.(Optional) | No |
|
useUserLevelCredential | Use User level credentials (fisCustomerId and fisLocationId) if available. | No |
false
|
preventMultiAttempt | Prevent multiple verification attempt. If true, will send failed response directly if failed before in same txn. | No |
false
|
recordResponse | Record response text as submission properties. | No |
true
|
Inputs
Name | Description | Required |
---|---|---|
task | The task to be performed. Valid values are:
|
Yes |
applicantRole | The Applicant role for distinguish different applicants request in the same session. | No |
Personal Details Inputs for question task
|
Personal details of the individual being identified. These parameters are required when task is question Date of birth is expected to be received in Avoka standard format (yyyy-MM-dd) E.g. 2016-07-21. |
Yes |
answers for answer task |
The answers to questions. This parameter is required when task is answer . Array of JSON objects with the following format qid: question id from previous response cid: selected answer choice id of the question id above |
Yes |
Outputs
Name | Description |
---|---|
questions | The questions get returned for the user to answer. It's available in the following case:
[ |
attemptsLeft | The number of attempts left for calling this service in the same session (Only available when maxAttemptNumber is configured on server). If this value returns as 0 , the server will reject any additional requests and give it a SYSTEM_ERROR with errorCode: EXCEEDED_NUMBER_OF_ATTEMPTS .Please also note that the attempts number counts separately for each applicant. There is a parameter called Applicant Role Name inside Iovation Verify Block and you need to make sure each block has an unique applicant role name. |
verifyStatus | The status of the ID verification for this individual with possible values: [ VERIFIED | FAILED ]. Only available in answer task if verification comes to conclusion |
executionStatus | The status of the service execution [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ]. Successful execution will be denoted by a SUCCESS value. 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. |
errorCode | Error code for some specific error case. Not always available. In this service, EXCEEDED_NUMBER_OF_ATTEMPTS gets returned if current attempt number exceeds maxAttemptNumber defined in the service. |
User Level Credential
By default, this service will send customerid and locationid values defined in service parameters. However it also supports send different customerid and locationid values for specific TM users. You can do this by:
- In TM, Click 'Forms' -> 'Property Types', Create two new Property Types as 'fisCustomerId' and 'fisLocationId', make them 'User' scope.
- Click 'Security' -> 'User Account', select a user, In 'User Profiles' tab, click the current profile, In 'User Properties' tab, set a new value for 'fisCustomerId' and 'fisLocationId'
- Once it's done, when this user login and use the FIS ChexSystems service, it will send this user's customerid and locationid instead of default customerid and locationid in service paramerters.
Prevent Multiple Verification Attempt
When service parameter "preventMultiAttempt" set to true, it will prevent following verification request if any
previous verification is FAILED
in the same txn. If this is the case, it will not call FIS ChexSystems
IDV web service, instead, will return FAILED
response immediately. On TM server it will also write
submission property "FisIdv.(roleName.)multipleVerifyAfterFail"="true" in current txn.
There is also another service parameter maxAttemptNumber when set to a positive number, it will control the maximum number an applicant can perform the FIS IDV/OFAC service in the same transaction and returns DATA_ERROR when max attempt exceeded with errorCode: EXCEEDED_NUMBER_OF_ATTEMPTS. Its default value is -1 which means no restriction. If this parameter is set to positive number, it will also include The number of attempts left for calling this service in result JSON.
Service Connection
Compatibility
Module | Compatibility |
---|---|
Manager | 5.0.2 |
Service Parameters
Name | Description | Required | Default |
---|---|---|---|
fisCustomerId | Customer Identifier, assigned by Decision Solutions to identify the financial institution. | Yes |
10000000
|
fisStaging | Set to false if it's a production system, otherwise leave it to true for all testing environment. This will affect data sending to QualiFile service | Yes |
true
|
fisLocationId | Unique identifier of the person doing the inquiry.(Optional) | No |
|
useUserLevelCredential | Use User level credentials (fisCustomerId and fisLocationId) if available. | No |
false
|
preventMultiAttempt | Prevent multiple verification attempt. If true, will send failed response directly if failed before in same txn. | No |
false
|
recordResponse | Record response text as submission properties. | No |
false
|
Inputs
Name | Description | Required |
---|---|---|
applicantRole | The Applicant role for distinguish different applicants request in the same session. | No |
Personal Details Inputs:
|
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. |
Yes |
Outputs
Name | Description |
---|---|
attemptsLeft | The number of attempts left for calling this service in the same session (Only available when maxAttemptNumber is configured on server). If this value returns as 0 , the server will reject any additional requests and give it a SYSTEM_ERROR with errorCode: EXCEEDED_NUMBER_OF_ATTEMPTS .Please also note that the attempts number counts separately for each applicant. There is a parameter called Applicant Role Name inside Iovation Verify Block and you need to make sure each block has an unique applicant role name. |
idvVerifyStatus | The status of the ID verification for this individual with possible values: [ VERIFIED | FAILED ] |
idvNoRecordFound | Boolean value of whether the transaction is "No Record Found". |
ofacStatus | The status of the OFAC check for this individual with possible values: PASSED | FAILED ] |
executionStatus | The status of the service execution [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ]. Successful execution will be denoted by a SUCCESS value. 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. |
errorCode | Error code for some specific error case. Not always available. In this service, EXCEEDED_NUMBER_OF_ATTEMPTS gets returned if current attempt number exceeds maxAttemptNumber defined in the service. |
FIS passwords expire after 12 months and must be refreshed. FIS provide an API to check the expiry date of the current password and generate a new password if the expiry date is imminent. This service is provided to facilitate regular checks against the FIS password expiry API and to either warn of imminent expiry or automatically refresh the password before expiry (default). The expiry threshold is set to 30 days but can be adjusted if required.
In order to activate this service, a scheduled job must be created that calls this service on a periodical basis (we recommend once per day). The first time the service is run within the expiry threshold window, the auto-update or warning notification will be triggered. The fisAutoUpdatePassword parameter is used to control which of these modes will be used at execution time.
Auto-update mode:
In this mode, when the password is about to expire, it will trigger the change password service to refresh the password and automatically update the Service Connection with the new password. A notification email containing the new password will be sent to the pre-configued administrator email addresses specified in the service parameters.
If for some reason the automatic update of the password fails at the FIS API layer, a warning email will be generated.
Warning only mode:
In this mode, when the password is about to expire, it will only send a warning email to advise the administrators of the imminent expiry.
Managing Shared passwords across multiple Avoka environments
FIS provide a single production environment and a single non-production environment only. If you are managing multiple Avoka non-production environments then you will need to use the same FIS credentials across each of these. This presents an issue for the auto-update mode because the first environment to use the APIs to generate the new password will break the other environments.
To manage this issue we recommend that one of the non-production environments be selected as the primary environment and set to use the auto-update mode, while all others are set to warn only. When the primary environment generates the new password, a notification email is sent to the configured mailboxes containing the new password and asking the recipients to ensure that all dependant environments are updated. This is a manual process as the Avoka environments are unaware of each other and in some cases may be logically isolated from each other.
Note that as soon as the new password has been generated in the primary environment, any environments that share that password will be non-functional until the password is manually updated.
See also Managing multiple service endpoints and credentials for external service calls.
Service Connection
Compatibility
Module | Compatibility |
---|---|
Manager | 5.0.2 |
Service Authentication | V002 |
Service Parameters
Name | Description | Required | Default |
---|---|---|---|
fisExpiryThreshold | Expiry threshold in days. Trigger password update service or Send notification email if expire date is less than this value from today. | Yes |
30
|
fisAutoUpdatePassword | If set to true, will call 'FIS Change Password Service' to update the password automatically if within 'fisExpiryThreshold'. Otherwise will send notification email. | No |
true
|
fisNotifyMailboxes | One or more email addresses, separated by commas. The specified mailboxes will recieve any notification emails generated by this service. | Yes |
[email protected]
|
fisExpiryWarningEmailSubject | Notification email subject of password expiry warning. | Yes |
Please change your password for FIS service.
|
fisExpiryWarningEmailBodyTemplate | Notification email body template of password expiry warning. | Yes |
The FIS connectivity password is due to expire on ${expireDate}. Please ensure a new password is configured in the following Transact Manager environment before that time to avoid any service outage as a result of password expiry.
|
fisNewPasswordEmailSubject | Notification email subject when password auto-update is triggered and update at FIS successfully. | Yes |
FIS password updated.
|
fisNewPasswordEmailBodyTemplate | Notification email body template when password auto-update is triggered and update at FIS successfully. Must contains ${newPassword} in order to copy password to all other non auto update environment. | Yes |
The following FIS connectivity password has been automatically re-issued as the expiry of the old password was imminent:
|
Provides FIS ChexSystems QualiFile Verification.
User Level Credential
By default, this service will send customerid and locationid values defined in service parameters. However it also supports send different customerid and locationid values for specific TM users. You can achieve this as follows:
- In TM, Click 'Forms' -> 'Property Types', Create two new Property Types as 'fisCustomerId' and 'fisLocationId', make them 'User' scope.
- Click 'Security' -> 'User Account', select a user, In 'User Profiles' tab, click the current profile, In 'User Properties' tab, set a new value for 'fisCustomerId' and 'fisLocationId'
- Once it's done, when this user login and use the FIS Qualifile service, it will send this user's customerid and locationid instead of default customerid and locationid in service paramerters.
Prevent Multiple Verification Attempt
When service parameter "preventMultiAttempt" set to true, it will prevent following verification request if any
previous verification is DECLINE
in the same submission. If this is the case, it will not call QualiFile
web service, instead, will return DECLINE
response immediately. On TM server it will also write
txn property "FisQualiFile.(roleName.)multipleVerifyAfterFail"="true" in current txn.
There is also another service parameter maxAttemptNumber when set to a positive number, it will control the maximum number an applicant can perform the FIS QualiFile service in the same transaction and returns DATA_ERROR when max attempt exceeded with errorCode: EXCEEDED_NUMBER_OF_ATTEMPTS. Its default value is -1 which means no restriction. If this parameter is set to positive number, it will also include The number of attempts left for calling this service in result JSON.
Service Connection
Compatibility
Module | Compatibility |
---|---|
Manager | 5.0.2 |
QualiFile Consumer | N003 |
Service Parameters
Name | Description | Required | Default |
---|---|---|---|
fisCustomerId | Customer Identifier, assigned by Decision Solutions to identify the financial institution. | Yes |
10000000
|
fisStaging | Set to false if it's a production system, otherwise leave it to true for all testing environment. This will affect data sending to QualiFile service | Yes |
true
|
fisStrategyTypeId | Strategy type Id is only used in customer QualiFile implementations. | No |
|
fisLocationId | Unique identifier of the person doing the inquiry.(Optional) | No |
|
fisDataErrorList | A set of data error codes separated by comma. | No |
8102,8103,8104,8105,8106,8107,8108,8109,8110,8112,8113,8139,8151
|
fisAcceptValue | In which value would be treated as ACCEPT state | Yes |
ACCEPT
|
fisReviewValue | In which value would be treated as REVIEW state | Yes |
REVIEW
|
fisDeclineValue | In which value would be treated as DECLINE state | Yes |
DECLINE
|
fisQualiFileExceptionScoreMap | Map QualiFile Exception Score Code(9999/9992/9995/9998) into one of the decision code(ACCEPT,REVIEW,DECLINE). Format is QualiFileExceptionCode1:decisionCode1,QualiFileExceptionCode2:decisionCode2 | Yes |
9999:ACCEPT,9992:REVIEW,9995:REVIEW,9998:REVIEW
|
useUserLevelCredential | Use User level credentials (fisCustomerId and fisLocationId) if available. | No |
false
|
preventMultiAttempt | Prevent multiple verification attempt. If true, will send failed response directly if failed before in same txn. | No |
false
|
recordResponse | Record response text as submission properties. | No |
false
|
maxAttemptNumber | Max number that allowed to initiate Iovation check in a single session for each applicant. -1 means no limit. | Yes |
-1
|
Inputs
Name | Description | Required |
---|---|---|
applicantRole | The Applicant role for distinguish different applicants request in the same session. | No |
Personal Details Inputs:
|
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. |
Yes |
Outputs
Name | Description |
---|---|
attemptsLeft | The number of attempts left for calling this service in the same session (Only available when maxAttemptNumber is configured on server). If this value returns as 0 , the server will reject any additional requests and give it a SYSTEM_ERROR with errorCode: EXCEEDED_NUMBER_OF_ATTEMPTS .Please also note that the attempts number counts separately for each applicant. There is a parameter called Applicant Role Name inside Iovation Verify Block and you need to make sure each block has an unique applicant role name. |
qualiFileStatus | The status of the verification for this individual with possible values: [ ACCEPT | REVIEW | DECLINE ] |
executionStatus | The status of the service execution [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ]. Successful execution will be denoted by a |
errorMessage | When a DATA_ERROR is experienced, this value may provide more detail on the nature of the error. |
errorCode | Error code for some specific error case. Not always available. In this service, EXCEEDED_NUMBER_OF_ATTEMPTS gets returned if current attempt number exceeds maxAttemptNumber defined in the service. |
Service Connections
The following service connections are used by this package.
Property Name | Description | Required |
---|---|---|
Type | HTTP Endpoint | Yes |
Endpoint |
FIS web service end point. You don't need to add /chexsystems as suffix since the service will add it automatically.
|
Yes |
Username | Username for FIS web service | Yes |
Password | Password for FIS web service | Yes |