Iovation TAF v1.4

Introduction

Iovation - FraudForce and SureScore

Catch more fraudsters while decreasing false declines. Iovation's dynamic device database is informed by the context, behavior and past reputation of more than 5 billion devices; that knowledge is then used by FraudForce to alert you of potential fraud based on the device attempting to connect.

FraudForce provides the following capabilities and benefits:

  1. Evasion Detection - Stop fraudsters hiding behind proxy servers, TOR networks, VPNs, mobile VMs, emulators or other anonymizing technology.
  2. Recognize Devices Instantly - FraudForce analyze thousands of permutations of device attributes to accurately recognize a device while minimizing false positives.
  3. Advanced Analytics - Detect specific fraud patterns, such as if a particular device was used to access multiple accounts within a certain time period.
  4. Flexible business rules editor - Enables fraud analysts to react immediately to new threats.
  5. Real-time Risk Insight - Alerts for location mismatches, time zone and IP address changes & activities from high-risk areas, IPs or ISPs.
  6. Maximize End-user Privacy - Recognize and register devices using deep digital intelligence without needing to collect and store large amounts of personal information.

SureScore provides the following capabilities and benefits:

  1. SureScore, is a powerful machine learning platform, monitors transactions and activity patterns that predict fraudulent behavior. Iovation models analyze hundreds of device attributes and are trained on millions of confirmed fraud reports to deliver a single risk score.
  2. Reduce your review queue and avoid costly step-ups by identifying low-risk transactions. Predictive machine learning shows which connections are fraudulent and which can be trusted.
  3. Predictive machine learning-based insights allow you to treat new customers like a well-known VIP. Make it easier for them to open an account, log in, make a purchase or take advantage of a promotion.

Package features include:

  1. Multiple triggers of the Iovation FraudForce service
    1. It is now possible to trigger the check multiple times and on different parts of any form. Whether this form is a part of a larger collaboration job or stand-alone.
    2. Also, certain sections of the application may have different rule sets, using integration points; you may decide to soften the rules depending on the section of the application.
  2. Max attempt control
    1. Limit the number of calls an application can make, this will save you unnecessary costs. In case the service has provided a result from one device, there's no need to trigger it again and again. This feature will ensure you are paying the right cost for each application using Iovation FraudForce.
  3. Insights Milestones and Segmentation
    1. This package includes Pre-built Segments and Milestones to assist you to evaluate the quality of the service.
    2. This feature helps ensure the right business rules are set in Iovation. For example, if too many applications have been set to review by FraudForce, it may be related to a misconfiguration which can easily be fixed.
    3. When monitoring the application success using Segments and Milestones, Insights will give you a clear view of the total of accepted, reviewed and declined applications. It will also show you the number of issues that occurred while attempting to use the service.
  4. Flexible FraudForce insights fields to provide additional information to maximise the benefits of FraudForce
    1. These are not mandatory, but most of them are taken as part of the normal personal details captured for every application. You can pick the relevant fields, whitelist them and get better results from Iovation.
  5. Server and Client value objects
    1. This will help to use the results in an external service, for example, a decision service.
  6. 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.
  7. TAF + Maven support
  8. Exchange regression suit - automating over 40 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 Integration Framework. It is used to develop integrations in Transact 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:

ModuleCompatibilityNotes
Journey Manager17.10.9 or above
Journey Maestro18.05.7 or above
Narration Controller1.4.3 or above
Narrator Componentlatest with support of form actions
TIF version1.6.1 or above
Configuration Service1.1.0 or above

Release Notes

Version 1.4 Sep 30, 2020

  • Fixed a bug to support multiple ip addresses with space in between.

Version 1.3 Mar 26, 2020

  • Configuration service support.
  • Added support for disabling milestone events optionally.

Version 1.2 Dec 4, 2019

  • Support getting the last ip address correctly in multiple proxy case.

Version 1.1 May 3, 2019

  • Added SureScore product which predicts risk and identifies good consumers with machine learning.
  • Added Http Audit feature.

Version 1.0 Apr 18, 2019

  • Baseline release.



Installation

Exchange Installation

This package should be installed as a single archive via the Avoka Exchange. 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 Transact Manager under the Services >> Service Connections menu item.
  5. Installation of any included Maestro libraries requires you to login to you 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 iovationInsightParametersWhiteList, 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

  • In your Maven project, add the following dependencies in pom.xml as below in order to import and consume Iovation result through Iovation VO this package provides.

  • 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": "Example Application Narrative",
        "version": "1.0.0",
        "pages": [
            {
                "name": "GetStarted",
                "preActions": [],
                "postActions": [
                    {
                        "name": "Iovation - Check Txn Details",
                        "version": "1.3.0",
                        "params": {
                            "Insight.email": "${txn.formDataMap.get('email')?:''}",
                            "Insight.homePhoneNumber": "${txn.formDataMap.get('homePhoneNumber')?:''}",
                            "Insight.officePhoneNumber": "${txn.formDataMap.get('officePhoneNumber')?:''}",
                            "ApplicantRole": "Primary"
                        }
                        
                    }
                ],
                "nextPages": [
                    "Success"
                ]
            }
            ...
        ]
    }
    

    High Level Diagram

    Below are the process flow diagrams for Check Txn Details. This gives an insight into the design of the components.

    Check Txn Details

    CSP Configuration

    The Content Security Policy (CSP) response header helps you reduce XSS risks on modern browsers by declaring what dynamic resources are allowed to load via a HTTP Header, thereby protecting your solution from a range of vulnerability attacks.

    The Iovation integration loads third party JavaScript library which is injected to the form, and this will get blocked if the form header includes strict Content Security Policy (CSP) settings. By default, Avoka Transact has strict CSP settings configured so these will likely need to be modified in order to enable the LinkedIn integration.

    You can configure CSP settings in Transact Manager at a system wide level via the 'Form Submission Access Controller' service, or at an Organization level in the Security tab. The following Sample CSP demonstrates how to enable the Iovation JavaScript integration:

    script-src 'self'  https://mpsnare.iesnare.com; object-src 'none'

    For more information see CSP on The Avoka Community

    Configuring the Reverse Proxy

    In order to properly deliver the Iovation first party dynamic components, you must tunnel requests through TM server to Iovation's servers. This is done by setting up a reverse proxy on TM to get the files from an iovation-hosted server.

    Example: Configuring a Reverse Proxy in Apache
    Edit the Apache configuration file (httpd.conf) and enable the following modules:

    LoadModule proxy_module modules/mod_proxy.so
    LoadModule proxy_http_module modules/mod_proxy_http.so
    SSLProxyEngine On
    Add the following lines, in the main configuration or VirtualHost directive.
    • Test:
      ProxyPassMatch ^.*/iojs/(.*)$ https://ci-first.iovation.com/$1
    • Production:
      ProxyPassMatch ^.*/iojs/(.*)$ https://first.iovation.com/$1

    You can check if reverse proxy server is configured correctly by inspecting browser's console in the rendered form which shouldn't have any javascript loading errors.

    Iovation Check Transaction Details

    Configuration

    Maestro Assets

    Use the following procedure to configure Iovation Check Transaction in your form:

    • In Maestro, place the Iovation Check Transaction component onto your form.
    • There is nothing to configure for this component in single applicant case, the main purpose for this component is to load Iovation first and third-party javascript in order to generate a black box value persisted in the form data and used later in the fluent function. By default there is no applicant role defined.
    • This component also supports multiple instances to represent different applicant roles. In that case, you need to add the applicant role key as the prefix of the root level of the component id in the following format:
      applicantRole_iovation_checkTxnDetails

      For example, if you define PrimaryApplicant as the applicant role key, you need to change the maestro component id to primaryApplicant_iovation_checkTxnDetails. Also make sure when you call the Iovation TAF - Check Transaction Details fluent function, send the input parameter ApplicantRole: "PrimaryApplicant"

      Note: the Maestro entity id needs to begin with lowercase, that's why the above id begins with primaryApplicant_ in case applicant role is PrimaryApplicant

    • In the result block, there are couple of data fields coming from the result that you can use in your form such as executionStatus, verifyStatus, attemtpsLeft, etc. We've also included the default error messages (text display fields) for system error and data error.
    • 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.

    Max Verification Attempt

    The service within the package supports the Max Verification Attempts feature.

    This feature is meant to limit the cost involved in initiating calls to Iovation from a single transaction.

    Configuration

    1. Set the maxAttemptNumber to a positive number in the service parameter.
    2. If you don't want to put any restriction, set it to -1.
    3. If you want to alert the applicant on how many attempts are left, you can see the number of attempts left in both JSON result and Data Field: attemptsLeft in Maestro component.
    4. 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.

    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 named httpAudit on the transaction for which the request was made.

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

    [
        {
            "serviceName": "Iovation CheckTxnDetails",
            "executionTimestamp": "2019-05-02 17:43:58 AEST",
            "durationMillis": 147,
            "request": {
                // Request Details
            }
            "reseponse": {
                // Response Details
            }
        },
        {
            "serviceName": "Iovation CheckTxnDetails",
            // Etc...
        }
    ]
    

    See the documentation for the Iovation TAF - Check Transaction Details service for information on how to enable this feature.

    Insights

    Milestone events

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

    NameTrigger
    Iovation CheckTxnDetails StartOn receiving an Iovation check request
    Iovation CheckTxnDetails CompleteWhen Iovation check get executed successful (Accept/Review/Decline)

    Note: You can optionally turn off all milestones inside the Exchange services by setting the service parameter: disableMilestones to true if you prefer a simplified diagram in Journey Analytics.

    Segment events

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

    Note: Please make sure you've added the following segment name and valid values to Insights segment whitelist before using this component. For more information, please refer to Insights Preferences

    NameValueTrigger
    Iovation CheckTxnDetailsAcceptWhen Iovation returns accept result
    Iovation CheckTxnDetailsReviewWhen Iovation returns review result
    Iovation CheckTxnDetailsDeclineWhen Iovation returns decline result

    Service Txn properties/ Server VO

    The table below describes Check Txn Details server VO fields stored in the Form XML Data and also stored in transaction properties.

    NameDescriptionFormatNotes
    Iovation.CheckTxnDetails.Result.executionStatusThe status of the service execution with possible values: [ SUCCESS | DATA_ERROR | SYSTEM_ERROR ]String
    Iovation.CheckTxnDetails.Result.verifyStatusIovation check result with possible values: [ ACCEPT | REVIEW | DECLINE ]String
    Iovation.CheckTxnDetails.Result.accountCodeUnique identifier for the end-user's account. This value is echoed back from the request.String
    Iovation.CheckTxnDetails.Result.idA unique ID for the request, this value is from responseString
    Iovation.CheckTxnDetails.Result.trackingNumberA unique ID assigned to the transaction that can be used to locate the transaction in searches and reports.String
    Iovation.CheckTxnDetails.Result.reasonA user-specified value describing the rule that contributed the most to the result.String
    Iovation.CheckTxnDetails.Result.resultResult of the transaction risk or auth check, with a recommendation to allow ( A ), deny ( D ), or review ( R ) the transaction.StringThis value is directly from raw response
    Iovation.CheckTxnDetails.Result.statedIpThe end-user's stated IP addressString
    Iovation.CheckTxnDetails.Result.scoreTotal transaction score for the rulesetString
    Iovation.CheckTxnDetails.Result.rulesMatchedNumber of rules that were triggered.String
    Iovation.CheckTxnDetails.Result.sureScorethe SureScore outcome for the transaction for SureScore subscribersString
    Iovation.CheckTxnDetails.Result.errorCodeError code String When a DATA_ERROR or SYSTEM_ERROR is experienced, this value provides the error code.
    Iovation.CheckTxnDetails.Result.errorMessageError MessageStringWhen a DATA_ERROR or SYSTEM_ERROR is experienced, this value may provide more detail on the nature of the error.
    Iovation.CheckTxnDetails.Result.rawResponseRaw responseStringOptional field controlled by the connection property flag recordResponseInTxnXML to store raw response in server VO
    httpAuditHTTP Audit LoggingStringOptional field records information about each HTTP request call made in the execution of a service

    Configuration Service Support

    This package supports the configuration service. Please make sure you follow the instruction below to setup your configuration service correctly.

    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 package will just be keep adding content into the existing service parameter.

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

      "iovation": [
        {
          "serviceKey": "txn",
          "serviceName": "Iovation TAF - Check Transaction Details",
          "serviceParamKeyMap": {
            "recResInXml": "recordResponseInTxnXML",
            "recResInProp": "recordResponseInTxnProperties",
            "subscriberAccount": "iovationSubscriberAccount",
            "defIntPointName": "iovationDefaultIntegrationPointName",
            "defServiceId": "iovationDefaultServiceId",
            "insightParamList": "iovationInsightParametersWhiteList"
          }
        }
      ]
    

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

        {
          "name": "iovation-txn|1.3.0-conn.endpoint",
          "description": "Service connection Endpoint for iovation checktxn service",
          "value": "",
          "type": "String",
          "bind": false,
          "required": true,
          "clearOnExport": false,
          "readOnly": false
        },
        {
          "name": "iovation-txn|1.3.0-conn.username",
          "description": "Service connection Username for iovation checktxn service",
          "value": "",
          "type": "String",
          "bind": false,
          "required": true,
          "clearOnExport": false,
          "readOnly": false
        },
        {
          "name": "iovation-txn|1.3.0-conn.password",
          "description": "Service connection password for iovation checktxn service",
          "value": "",
          "type": "Password",
          "bind": false,
          "required": true,
          "clearOnExport": false,
          "readOnly": false
        },
        {
          "name": "iovation-txn|1.3.0-subscriberAccount",
          "description": "The iovation-assigned identifier of the organisation requesting the check. This provides an audit trail.",
          "value": "",
          "type": "String",
          "bind": false,
          "required": false,
          "clearOnExport": false,
          "readOnly": false
        },
        {
          "name": "iovation-txn|1.3.0-defIntPointName",
          "description": "Default integration point name that specifies which set of business rules to use when evaluating transaction risk.",
          "value": "",
          "type": "String",
          "bind": false,
          "required": false,
          "clearOnExport": false,
          "readOnly": false
        },
        {
          "name": "iovation-txn|1.3.0-defServiceId",
          "description": "Default service id representing different department under the same subscriber get used for the iovation.",
          "value": "",
          "type": "String",
          "bind": false,
          "required": false,
          "clearOnExport": false,
          "readOnly": false
        },
        {
          "name": "iovation-txn|1.3.0-insightParamList",
          "description": "",
          "value": "",
          "type": "String",
          "bind": false,
          "required": false,
          "clearOnExport": false,
          "readOnly": false
        },
        {
          "name": "iovation-txn|1.3.0-maxAttemptNumber",
          "description": "",
          "value": "2",
          "type": "String",
          "bind": false,
          "required": false,
          "clearOnExport": false,
          "readOnly": false
        },
        {
          "name": "iovation-txn|1.3.0-enableHttpAudit",
          "description": "With HTTP auditing enabled, details about each HTTP request (including request and response data) are stored in a transaction property as a JSON array against the relevant transaction.",
          "value": "",
          "type": "Boolean",
          "bind": false,
          "required": false,
          "clearOnExport": false,
          "readOnly": false
        },
        {
          "name": "iovation-txn|1.3.0-disableMilestones",
          "description": "Whether to disable Journey Analytics milestones for this service.",
          "value": "",
          "type": "Boolean",
          "bind": false,
          "required": false,
          "clearOnExport": false,
          "readOnly": false
        },
        {
          "name": "iovation-txn|1.3.0-recResInProp",
          "description": "",
          "value": "true",
          "type": "Boolean",
          "bind": false,
          "required": false,
          "clearOnExport": false,
          "readOnly": false
        },
        {
          "name": "iovation-txn|1.3.0-recResInXml",
          "description": "",
          "value": "true",
          "type": "Boolean",
          "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

    In order to enable the configuration service in your application, please define the following organisation property in your organisation ConfigServiceName. This is to define which configuration service you would like to use in your organisation. For example, if you decide to trigger MyCompanyServiceConfiguration as the configuration service, set the following organisation property.
      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.

    You can simply delete the organisation property ConfigServiceName to disable the configuration service in your organisation.

    Maestro Assets

    Iovation Check Transaction Library: exchange-iovation-taf Category: Iovation TAF

    Iovation Check Transaction Maestro component

    Services

    Iovation TAF - Check Transaction Details v1.3.0
    Provides Iovation Check transaction Details service.

    Service Connection

    Compatibility

    Module Compatibility
    Manager 17.10.9

    Service Parameters

    Name Description Required Default
    iovationSubscriberAccount The iovation-assigned identifier of the organisation requesting the check. This provides an audit trail. Yes OLTP
    iovationDefaultIntegrationPointName Default integration point name that specifies which set of business rules to use when evaluating transaction risk. Yes application
    iovationDefaultServiceId Default service id representing different department under the same subscriber get used for the iovation. No
    iovationInsightParametersWhiteList Transact Insight parameters names(separated by comma) that are accepted to be sent to Iovation service. Yes email,valueAmount,valueCurrency,homePhoneNumber,officePhoneNumber,mobilePhoneNumber,achRoutingNumber,alternateIp,billingCity,billingCountry,billingPostalCode,billingRegion,billingShippingMismatch,billingStreet,creditCardBin,emailVerified,eventId,homePhoneSmsEnabled,homePhoneVerified,mobilePhoneSmsEnabled,mobilePhoneVerified,officePhoneSmsEnabled,officePhoneVerified,onlineId,referrerUrl,securityPin,securityPinType,serviceId,sessionAlias,shippingCity,shippingCountry,shippingPostalCode,shippingRegion,shippingStreet,sku,tenantId,upc
    recordResponseInTxnProperties Record response as txn property. No false
    recordResponseInTxnXML Record response in Server VO and persisted in Txn XML. No false
    enableHttpAudit With HTTP auditing enabled, details about each HTTP request (including request and response data) are stored in a transaction property as a JSON array against the relevant transaction. No false
    maxAttemptNumber Max number allowed to initiate API calls in a single session for each applicant. -1 means no limit. Yes -1
    disableMilestones Whether to disable Journey Analytics milestones for this service. No false
    configServiceAppName AppName for configuration service. All exchange services use vendor code for AppName. Yes iovation

    Inputs

    Name Description Required
    IntegrationPointName The integration point name for the business rules to be used for the transaction. This value, if defined, overrides the default Integration point in service parameters.  Primary insight parameters No
    Insight.email The user's email address. No
    Insight.valueAmount The numeric value of a transaction. Up to 15 digits, followed by a decimal, followed by two digits.  No
    Insight.valueCurrency Currency type of the transaction. 3 character currency code. This must conform to ISO 4217.  No
    Insight.homePhoneNumber The user's home phone number. Plus sign followed by 4-20 digits. This must be a valid phone number, including country code. For example, a US number must begin with 1, followed by the 10 digit. No
    Insight.officePhoneNumber The user's office phone number. Plus sign followed by 4-20 digits. This must be a valid phone number, including country code. For example, a US number must begin with 1, followed by the 10 digit. No
    Insight.mobilePhoneNumber The user's mobile number. Plus sign followed by 4-20 digits. This must be a valid phone number, including country code. For example, a US number must begin with 1, followed by the 10 digit. No
    Insight.serviceId The specific service id representing different department under the same subscriber. This value, if defined, overrides the default service id in service parameter.  No
    Insight.xxx Any other valid transaction insight parameters could be sent as input parameter when adding "Insight." as prefix.

    xxx is the name of the parameter that matches Iovation Rest API insight parameter.

    For example, "Insight.achRoutingNumber" will be sending as achRoutingNumber inside "transactionInsight" map.

    When you integrate with this service, make sure the proper validation at front end has been applied to the related insight parameters according to the Iovation API specs.

    You can send multiple insight parameters separately.

    No
    Blackbox The device information generated by Iovation javascript. Normally you don't need to provide this blackbox value directly as input parameter, this fluent function automatically gets the black box value from iovation Maestro component.

    No

    Outputs

    Name Description
    data.verifyStatus The status of the iovation check result with possible values: [ ACCEPT | REVIEW | DECLINE ]
    data.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.

    data.errorMessage When a DATA_ERROR is experienced, this value may provide more detail on the nature of the error.
    data.errorCode When a DATA_ERROR is experienced, this value provides the error code.
    data.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 role.

    data.attemptsUsed The number of attempts performed so far.
    formStatus Form status

    Service Connections

    The following service connections are used by this package.

    Iovation REST
    Property Name Description Required
    Type HTTP Endpoint Yes
    Endpoint Iovation REST service end point.
    • Test: https://ci-api.iovation.com/fraud/v1/subs
    • Prod: https://api.iovation.com/fraud/v1/subs
    Make sure you change to the correct URL on production before using this service. Please note don't add your subscriberId or /checks in the end point, it will be added automatically by this service.
    Yes
    Username SubscriberId for Iovation REST service Yes
    Password SubscriberPasscode for Iovation web service Yes