RiskMinder Java Developer's Guide › Performing Risk Evaluation › Evaluating Risks and Performing Post-Evaluation

Evaluating Risks and Performing Post-Evaluation

To evaluate the risk associated with a transaction and to perform the subsequent post-evaluation, you need to use the RiskXActionAPI interface (in the com.arcot.riskfortAPI package. This interface represents the client-side interface to RiskMinder Server’s risk evaluation functionality and exposes the supported API for risk evaluation workflows.

To evaluate risk of a transaction and perform post-evaluation tasks:

1. Ensure that you have initialized the Risk Evaluation API by using the RiskFactory class.

   See "Initializing the Risk Evaluation API" in "Before You Begin" for more information.

2. If required, prepare the additional inputs for the transaction, by using the AdditionalInputs class in the com.arcot.riskfortAPI.AdditionalInputs package.

   See "Preparing Additional Inputs" in "Before You Begin" for more information.

3. Use the RiskFactory.getRiskXActionAPI() static method to obtain an object that implements the RiskXActionAPI interface.

   This method returns the RiskXActionAPI object created as a part of the RiskFactory API initialization.

4. Use the RiskXActionAPI.evaluateRisk() method to obtain an object of the RiskAssessment class.

   This method requires the following input parameters:

   1. Define and set the CallerID string variable, which will be used by your application for tracking purposes across calls.
   2. Invoke the buildDeviceSignature() method by using a DeviceContext object to build the JSON signature that you built, as discussed in "Collecting Device ID and DeviceDNA".
   3. Create a LocationContext object, and then invoke the LocationContext object's setIpAddress() method to set the IP address to that of the user's system.
   4. Create a UserContext object, and then use the UserContext object's setUserID() method to set a unique ID for the user.
   5. Create a TransactionContext object and, if required, set the necessary properties for the returned object by using the methods in this class (setAction() and setChannel()).
   6. If you are using extra information, then use the AdditionalInputs object that you created in Step 2. Set the necessary properties for the returned object by using the AdditionalInputs.put(name,value) method.

      These are additional inputs in form of name-value pairs. For example:

      MerchantID=id;MerchantCountry=country;MerchantName=name

5. Obtain the resulting RiskAssessment RiskAdvice object by using the RiskAssessment.getRiskAdvice() method.

   Important! If the advice is INCREASEAUTH, then your application must perform secondary authentication and pass the result of this authentication to RiskMinder by using the PostEvaluate() method.

6. Finally, use the RiskXActionAPI.postEvaluate() method to determine the final outcome of the transaction and return a PostEvaluateResponse object.

   The postEvaluate() method updates the Device Signature information for the user, if it changed and creates or updates user-device associations, if required.

   You will need to pass the result of secondary authentication to the method, if you performed any.

7. You can query the resulting PostEvaluateResponse object by using the PostEvaluateResponse.isAllowAdvised() method to:
   • Determine whether or not to permit the transaction to proceed.
   • Update the information related to the transaction in the RiskMinder database.

Handling Errors

Any errors that occurred during the execution of any of the Risk Evaluation API methods can result in one of the following two exceptions being thrown:

• RiskException is thrown if the error occurred at RiskMinder Server-end. In this case, the SDK only "relays" the information to your code. The RiskException object has getReasonCode, getResponseCode,and getTransactionId members that contain the reason code, error code, and transaction identifier (generated at RiskMinder Server-end) associated with the error that occurred.
• RFSDKException is, typically, thrown if the error occurred at the SDK-end. The RFSDKException object has getResponseCode and getTransactionId members that contain the error code and transaction identifier (generated at RiskMinder Server-end) associated with the error that occurred.

Sample Code for Risk Evaluation and Post Evaluation

Note: Refer to "Sample Code for Risk Evaluation and Post-Evaluation" in appendix for a detailed working code sample.

You can use the following sample code snippet to understand how to implement the risk evaluation and post-evaluation capability of RiskMinder in your application code.

public static void sampleCode() {
        String propertyLocation= "/properties/riskfort.risk-evaluation.properties";
        try {
             RiskFactory.initialize(propertyLocation);
             RiskXActionAPI riskXActionAPI = RiskFactory.getRiskXActionAPI();
             String callerId;
             UserContext userContext = new UserContext();
             LocationContext locationContext = new LocationContext();
             DeviceContext deviceContext = new DeviceContext();
             TransactionContext transactionContext = new TransactionContext();
             AdditionalInputs additionalInputs = new AdditionalInputs();
            
             // string used by the calling application for tracking across
              // calls
             callerId="MyApplicationTrackingId";
            
             // Unique identifier for the user. In case of a Bank it may be
              // user's bank account number
             // It may be name of the user in some other case.
             userContext.setUserId("USER1");
            
             // IP address of the user's machine, typically, extracted from
              // the HTTP header
             locationContext.setIpAddress(InetAddress.getByName("10.150.1.1"));
            
             // JSON Signature comes from mfp_json.js, in this example the
              // signature is hard coded
             // for the sample use.
             String jsonSignature = "{\"navigator\":{\"platform\":\"Win32\",\"appName\":\"Netscape\",\"appCodeName\":\"Mozilla\",\"appVersion\":\"5.0 (Windows; en-US)\",\"language\":\"en-US\",\"oscpu\":\"Windows NT 5.0\",\"vendor\":\"\",\"vendorSub\":\"\",\"product\":\"Gecko\",\"productSub\":\"20070312\",\"securityPolicy\":\"\",\"userAgent\":\"Mozilla/5.0 (Windows; U; Windows NT 5.0; en-US; rv:1.8.0.11) Gecko/20070312 Firefox/1.5.0.11\",\"cookieEnabled\":true,\"onLine\":true},\"plugins\":[{\"name\":\"Adobe Acrobat Plugin\",\"version\":\"7.00\"},{\"name\":\"Macromedia Director\",\"version\":\"10.1\"},{\"name\":\"Windows Media Player Plug-in Dynamic Link Library\",\"version\":\"\"},{\"name\":\"Macromedia Shockwave Flash\",\"version\":\"9.0\"},{\"name\":\"Java Virtual Machine\",\"version\":\"1.6.0\"}],\"screen\":{\"availHeight\":690,\"availWidth\":1024,\"colorDepth\":32,\"height\":768,\"pixelDepth\":32,\"width\":1024},\"extra\":{\"javascript_ver\":\"1.6\",\"timezone\":-330}}";
             deviceContext.buildDeviceSignature(jsonSignature,null,null);
             String userDeviceId="GPXp+4e0hzzxzh6YLlPZqKgXCGbBXB8E0ghZnFXHq8o3HLRaww6c4g==";
             // The device id collected from the user machine
             deviceContext.setDeviceID("HTTP_COOKIE", userDeviceId);
            
             // Providing the addition inputs.
             additionalInputs.put("MerchantID","id") ;
             additionalInputs.put("MerchantCountry","country") ;
             additionalInputs.put("MerchantName","name") ;
            
             transactionContext.setAction("Login");
             RiskAssessment riskAssessment=null;
             riskAssessment = riskXActionAPI.evaluateRisk(callerId , deviceContext, locationContext , userContext, transactionContext, additionalInputs);
             boolean secondaryAuthenticationStatus = true;
             String associationName = "USER1inHomePC";
            
             if (riskAssessment.getRiskAdvice().equals(RiskAssessment.RISK_ADVICE_INCREASEAUTH)) {
                         // then you may ask for secondary authentication
                         //if( secondaryAuthentication succeeded )
                         //          secondaryAuthenticationStatus = true;
                         //else
                         //          secondaryAuthenticationStatus = false
             }
            
             PostEvaluateResponse postEvaluateResponse =
                         riskXActionAPI.postEvaluate(callerId, riskAssessment,
                                                                         secondaryAuthenticationStatus, associationName);
             if( postEvaluateResponse.isAllowAdvised() ) {
                         //Allow the transaction to be completed
             }
             else {
                             //Deny and terminate the transaction
             }
            
             } catch (IOException e) {
            //Looks like the property file location is not valid
                e.printStackTrace();
             } catch (RiskException e) {
                //One of the RiskFort API calls broke
                e.printStackTrace();
             }
}