Previous Topic: Performing Risk Evaluation and Managing AssociationsNext Topic: Performing Post Evaluation

RiskMinder Web Services Developer's Guide › Performing Risk Evaluation and Managing Associations › Evaluating Risk

Evaluating Risk

To evaluate the risk associated with a transaction, you need to use the RiskFortEvaluateRiskSvc service (available through ArcotRiskFortEvaluateRiskService.wsdl.)

This section walks you through the following topics:

Preparing the Request Message

You must use the evaluateRiskRequest message to evaluate the risk associated with a transaction. The following table lists the elements of this request message.

Element

Mandatory

Description

callerId

No

Unique transaction identifier that your calling application can include. This identifier helps in tracking related transactions.

Device Context Elements

deviceContext

No

The end-user device details, as described by aggregatorID, deviceIDs, deviceSignature, and shortDeviceSignature.

deviceContext/
aggregatorID

No

The unique ID of the third-party vendor who provides account aggregation services by collating specified information of users across multiple enterprises.

deviceContext/
deviceIDs

No

Defined by the DeviceIDItem element, this element describes the unique identifier information to identify and track the device that the end user uses to log in to your online application and perform transactions:

  • deviceIDType: The string that identifies the storage type used to store the Device ID.
  • DeviceIDValue: The corresponding value for deviceIDType.

    Note: You can add more than one DeviceIDItem element, with deviceIDType and DeviceIDValue pairs.

deviceContext/
deviceSignature

No

The Machine FingerPrint (MFP) that RiskMinder’s MFP Collector builds this on the client side. This signature contains information related to the end-user’s device, such as browser details, system details, plug-in details, and screen width.

deviceContext/
shortDeviceSignature

No

The short form of the deviceSignature.

Location Context Elements

locationContext

No

The transaction location details, as described by clientIPAddress, longitude, latitude, continent, country, countryISO2, region, state, city, connectionType, and lineSpeed.

locationContext/
clientIPAddress

No

The Internet Protocol (IP) address of the end-user system in the public address space.

locationContext/
longitude

No

A floating point number, with positive numbers representing East and negative numbers representing West.

locationContext/
latitude

No

A floating point number, with positive numbers representing North and negative numbers representing South.

locationContext/
continent

No

The continent from where the transaction originated:

  • Africa
  • Antarctica
  • Asia
  • Australia
  • Europe
  • North America
  • Oceania (Melanesia, Micronesia, Polynesia)
  • South America

locationContext/
country

No

The country from where the transaction originated.

locationContext/
countryISO2

No

The two-letter country code (as defined in ISO 3166-1) from where the transaction originated.

locationContext/
region

No

The district or territory from where the transaction originated.

locationContext/
state

No

The first-level administrative division within each country (if one exists) from where the transaction originated.

locationContext/
city

No

The city from where the transaction originated.

locationContext/
connectionType

No

The type of data connection between the end-user’s device and their Internet Service Provider (ISP):

  • Satellite: High-speed broadband links between a user and a geosynchronous satellite.
  • OCX: The OC-3 circuits and OC-48 circuits that are used by large backbone carriers.
  • TX: Old links of type T-3 circuits and T-1 circuits.
  • Frame Relay: High-speed alternatives to TX.
  • Dialup: Modems that operate at 56kbps.
  • Cable: Cable modem broadband circuits, primarily offered by cable TV companies.
  • DSL: Digital Subscriber Line broadband circuits that include aDSL, iDSL, and sDSL.
  • ISDN: High-speed Integrated Services Digital Network technology with specialized modems and switches.
  • Fixed Wireless: Wireless connections where the location of the receiver is fixed.
  • Mobile Wireless: Wireless connections where the location of the receiver is mobile.

locationContext/
lineSpeed

No

The speed of the user’s Internet connection. This is based on connectionType.

User Context Elements

userContext

No

The user details, as described by orgName and userName.

userContext/
orgName

No

The name of the organization to which the end user belongs.

userContext/
userName

Yes

The name of the user who performed the transaction.

Transaction Context Elements

transactionContext

No

The transaction details, as described by action and channel.

transactionContext/
action

No

The type of transaction performed by the user, which can be:

  • Login
  • Wire Transfer
  • Any other value that you specify through your application

transactionContext/
channel

No

The channel from which the transaction originated:

  • Web: Transactions initiated through a Web browser. The originator may be a computer, smart phone, tablet, or set-top box.
  • SMS: Transactions initiated through SMS messaging.
  • App: Transactions initiated through smart phone, tablet application, or set-top box embedded applications.
  • 3DSecure: Online transactions initiated using credit card or debit card.
  • ATM: Transactions initiated through an Automated Teller Machine.
  • PoS: Transactions initiated at physical point of sale.

Administration Context Type Elements

adminContextType

No

The administrator details, as described by orgName, adminName, and locale, who initiated the Web service call.

adminContextType/
orgName

No

The name of the organization to which the administrator who initiated the Web service call belongs.

adminContextType/
adminName

No

The name of the administrator who initiated the Web service call.

adminContextType/
locale

No

The locale used by the administrator. The output message will be converted to this locale.

Additional Input Elements

additionalInput

No

Enables you to set additional inputs if you want to augment RiskMinder’s risk evaluation capability by specifying additional information. In such cases, you must set the extra information in name-value pairs.

  • name: The name with which you want to create the key pair.
  • value: The corresponding value for name.

    Note: You can add more than one of these elements.

Invoking the Web Service

To evaluate the risk associated with a transaction:

  1. (Optional) Include the authentication and authorization details in the header of the evaluateRisk operation. See "Managing Web Services Security" for more information on the header elements.
  2. Use the evaluateRiskRequest elements to set the required information, as listed in the table.
  3. Use the evaluateRiskRequest message and construct the input message by using the details specified in preceding step.
  4. Invoke the evaluateRisk operation of the RiskFortEvaluateRiskSvc service to perform risk evaluation.

    This operation returns the evaluateRiskResponse message that includes the risk assessment elements and the success result. See the following section for more information on the response message.

Interpreting the Response Message

The response message, evaluateRiskResponse, returns the risk assessment elements and the success result in the SOAP envelope header. These elements are explained in the following table. The SOAP body returns a success message if the operation was performed successfully. If there are any errors, then the riskfortFault response is returned. See appendix, "Exceptions and Error Codes" for more information on the SOAP error messages.

Element

Description

Risk Assessment Elements

riskAssessment

Contains the following details of the transaction:

  • advice
    An action (ALERT, ALLOW, DENY, INCREASEAUTH) suggested by the Risk Assessment module after evaluating the score of the transaction.
  • outputDeviceID
    The Device ID (cookie) information for the device.
  • score
    The score generated based on device details, location details, and user details.
  • matchedRuleMnemonic
    The rules that matched and for which RiskMinder flagged the transaction as risky.
  • ruleAnnotation
    The result of execution of all rules (or the reason for score and advice).
  • transactionID
    The unique identifier of the transaction.
  • deviceContext
    The gathered Machine FingerPrint (MFP) of the end-user’s device.
  • locationContext
    The gathered location details where the device was used to perform the transaction.
  • userContext
    The gathered details of the user who performed the transaction.

RiskFort Success Elements

riskFortSuccess

Contains the following information related to the result of the operation:

  • successMessage
    A string that defines the status of the operation.
  • transactionID
    The unique transaction identifier.