Understanding the Building Blocks of Rules
This topic explains the basic concepts that you need to understand before you build any rules and covers the following sub-topics:
cara
This topic explains the basic concepts that you need to understand before you build any rules and covers the following sub-topics:
2
Basic Rule Concepts
Before you build a rule, you must understand these basic concepts:
What Are Rules
Each
rule
is a pre-configured logic that returns a Boolean value. For a risk evaluation request from your application, this logic is applied to the incoming transaction data in the request. Each rule returns TRUE if the rule matched, and FALSE, if it did not.During scoring, Evaluation rules are scored in the order of priority until a match is detected.
Characteristics of a Rule
Every rule in RA has three specific characteristics that govern how the rule is processed:
- RulesetEach rulemustbelong to a Ruleset. This choice of the Ruleset determines the options that are available for a rule.
- Rule Implementation(at global or organization level)This characteristic determines whether the rule is applicable at the global level (available as a template to organizations) or at the level of individual organizations.
- Rule TypeThis characteristic determines the capability and scope of the rule, and is closely associated with Custom Rules added by using the Rule Builder.
Types of Rules Supported in RA
RA uses rules to evaluate the risk associated with each transaction. These rules can be broadly categorized into the following categories:
Out-of-the-Box Rules
These are
terminating rules
. In other words, if any Evaluation rule matches (returns True) during scoring, then the Risk Engine stops scoring the following rules in this category and generates a Risk Score corresponding to the matched rule.The out-of-the-box rules can be categorized as:
Configurable Predefined Rules
The following table lists the out-of-the-box rules that are installed and deployed by default when you install RA.
Rule Name
(Display Name)
| Rule Mnemonic
(Short Name)
| Rule Description
|
Exception User Check | EXCEPTION | An organization may choose to temporarily exclude a user from risk evaluation for a specified time interval. For example, a user might need to travel to a Negative Country. Such users are added to the Exception User List , and are referred to as exception users .If found in the Exception User List, by default, RA returns a low Score and the ALLOW advice for the transactions originating from exception users. |
Untrusted IP Check | UNTRUSTEDIP | This list constitutes the IP addresses that originate from anonymizer proxies or have been the origin of known fraudulent or malicious transactions in the past. Transactions originating from configured negative IP addresses receive a high score and the advice is Deny. |
Negative Country Check | NEGATIVECOUNTRY | This list comprises the countries that have been known to be origins of significant number of frauds in the past. RA derives the country information based on the input IP address, and then uses this data to return a high risk score for online transactions originating from these "negative" countries. Transactions originating from configured negative countries receive a high score and the advice is Deny. |
Trusted IP/Aggregator Check | TRUSTEDIP | Transactions originating from IP addresses "trusted" to the organization receive a low score, by default, and the advice is Allow. Many enterprises use the services of account and data aggregation service providers to expand their online reach. The originating IP addresses when users log in from a protected portal versus when they come in through such aggregators are different. Transactions originating from aggregators "trusted" to the organization receive a low score, by default, and the advice is Allow. |
Device MFP Match | SIGMATCH | Checks if the match percentage between the input signature and the corresponding stored signature is GREATER_OR_EQUAL to a specified Signature Pass Threshold. Note: The short form of MFP must be passed along with long form of MFP for risk evaluation. The SIGMATCH rule does not trigger if only short form of MFP is passed. |
User Velocity Check | USERVELOCITY | Frequent use of the same user ID could be an indication of risky behavior. For example, a fraudster might use the same user ID and password from different devices to watch a specific activity in a targeted account. Too many transactions originating from the same user within a short (configurable) interval receive a high score and the advice is Deny. |
Device Velocity Check | DEVICEVELOCITY | Frequent use of the same device could also be an indication of risky behavior. For example, a fraudster might use the same device to test multiple combinations of user IDs and passwords. Administrators can now configure RA to track this behavior, as well. Too many transactions originating from the same user device within a short (configurable) interval receive a high score and the advice is Deny. |
Zone Hopping Check | ZONEHOPPING | If a user logs in from two long-distance locations within a short time span by using the same user ID, this might be a strong indication of fraudulent activity. In addition, a User ID can also be shared, in which case, RA understands that the two people sharing the same User ID can be in geographically different locations and responds with an appropriate response. Transactions originating from the same user from locations that are far apart from each other within a short (configurable) interval receive a high score and the advice is Deny. |
Non-Configurable Predefined Rules
In addition to the preceding configurable rules, Risk Analytics also provides the following non-configurable rules. The following table lists the out-of-the-box non-configurable rules that are installed and deployed by default when you successfully install and configure RA.
Rule Name (Display Name)
| Rule Mnemonic (Short Name)
| Rule Description
|
User Known | USERKNOWN | A known user is already registered in the RA database.If the user does not exist in the Risk Analytics database, then Risk Analytics returns ALERT. In this case, your application can either call the Risk Analytics API to create the user in Risk Analytics, or take an appropriate action. |
DeviceID Known | DEVICEIDCHECK | The Device ID is a device identifier string that RA generates and stores as a cookie on the end user’s system to identify and track the device that the end user uses for logging in to your online application to perform transactions.RA returns a low risk score for transactions originating from known devices and the advice is typically ALLOW. In other words, if a device (whose transaction is being evaluated) exists in the Risk Analytics database. This information is used for Machine FingerPrint match. |
User Associated with DeviceID | USERDEVICEASSOCIATED | Transactions originating from a known device (in other words, corresponding User-Device association exists in the RA database) that is associated with a user, and whose DeviceDNA matches, receive a low score, and the advice is ALLOW. Transactions originating from a known device that is not associated with a known user receive a medium score, and the advice is INCREASEAUTH. |
Custom Rules
In RA, new customized rules and logic can be either built by using the Rule Builder or can be built using Callouts. This section walks you through the two ways you can build a new rule or logic in RA. It covers the following topics:
Custom Rules Built Using Rule Builder
The out-of-the-box rules in RA are generic and are configured for evaluating risk based on the rules that are applicable to all. If you need industry-specific rules that are significantly different from those that RA provides out-of-the-box, then you need to build and deploy your own rules by using the
Rule Builder
.Unlike the out-of-the-box rules, these rules are installed, but not deployed automatically. Creating Custom Rules by Using Rule Builder guides you through the process of building custom rules.
Custom Evaluations Built Using Callouts
Based on your business requirements, you can write your own custom Evaluation logic and Scoring logic, which if implemented, will run at your application-end, independent of RA Transaction Server. These custom Evaluation or Scoring programs are known as
Callouts
that can also be implemented to interact with your application’s back-end system.The Callout framework is a part of Transaction Server and just like any other RA Evaluation rule, is loaded during the Server startup. It is implemented as a
.dll
or .so
file.Note:
RA is shipped with a basic Sample Callouts WAR
file (riskfort-5.0-sample-callouts.war
) that demonstrates how you can write and implement simple Evaluation and Scoring Callouts.Example of Callout Implementation
For example, in addition to tracking the origin of each transaction, a banking institution would also like to assess the risk of regular bank transactions and wire transfers based on the transaction amount. Say, the bank would like to evaluate all transactions more than $30,000 for risk, irrespective of whether they are regular transactions or wire transfers. In this case, in addition to using RA’s Negative Country, Untrusted IP, Zone Hopping, and Velocity checks, the institution can write an Evaluation Callout (within the scope of their application) to track this behavior.
What are Evaluation Callouts
Based on your business requirements, you can also write your own custom Evaluation logic, which will run at your application-end, outside of the context of the Transaction Server. RA executes this custom Evaluation Callout
after
all the out-of-the-box rules and your new rules have been executed. This Callout accepts results of all previous rules and Additional Inputs as input and returns:- Aresponse(SUCCESS/FAILURE)
- Amodifier string(extra information to be used by the Scoring Callout)
- Anannotation string(the reason or the description returned back to Transaction Server by your Callout implementation module).
See Configuring RA Callouts for detailed information on working with Evaluation Callouts.
How Evalution Callouts Work
An Evaluation Callout is executed as part of risk evaluation. If an Evaluation Callout is implemented, then:
- RA executes all Standalone and Combination rules and invokes the Callout framework.
- The RA Callout framework formats the data in XML format.
- The RA Callout framework performs an HTTP or HTTPS POST of the following information to your Evaluation Callout:
- Context information(such as User name, IP address, and Device ID) that is passed to each RA Evaluation rule.
- Rule resultsfor each Evaluation rule that was executed.
- Additional Inputs, if any, that are provided by the RA SDK to Transaction Server as input data.
- Your Callout uses the data passed by RA to process its custom logic.
- Your Callout then returns the following information to RA:
- Rule resultin the form of Y (SUCCESS) or N (FAILURE).
- Modifier stringwith additional information, if any, to be used by the Scoring Callout (if implemented.)Transaction Server does not process the modifier string at all. If a Scoring Callout also has been implemented, then Transaction Server POSTs this data to the Scoring Callout.
- Annotation stringthat contains the reason or the description sent back to Transaction Server.
This information is used for logging (in the database), reporting, and auditing purposes. - Transaction Server logs the information returned by your Callout.
What are Scoring Callouts
Based on your business requirements, RA also provides you the flexibility to add your own custom scoring logic, in addition to RA's standard scoring logic. You can do so with the help of
Scoring Callout
. By implementing a Scoring Callout, you can write your own custom scoring logic to process the Score, Advice, and risk-evaluation results generated by RA's standard scoring program. The Scoring Callout then returns the final risk Score, which can differ and will override the Score computed by RA's standard Scoring Engine.Like the Evaluation Callout, Scoring Callout is a custom rule that executes
last
, after the standard RA scoring program is completed and returns a final Score and Advice.See Configuring RA Callouts for detailed information on working with Scoring Callouts.
How Scoring Callouts Work
A Scoring Callout is executed
after
the standard RA Scoring logic has executed. If a Scoring Callout is implemented, then:- Transaction Server executes the standard Scoring program and invokes the Callout framework.
- The RA Callout framework formats the data in XML format.
- The RA Callout framework performs an HTTP or HTTPS POST of the following information to your Scoring Callout:
- Overall Scorecomputed by the standard RA built-in Scoring Engine.
- Rule resultsfor each Evaluation rule that was executed.
- Additional Inputs, if any, that are provided by the calling application as part of the evaluateRisk() API call.
- Modifier stringoriginally returned by the Evaluation Callout.
- Your Callout uses the data passed by RA to process its custom logic.
- Your Callout then returns the following information to RA:
- Final Scorein the form of an integer in the range [0 - 100].
The score returned by the Scoring Callout always overrides the Score computed by the RA Scoring Engine. If you want to retain the score computed by the RA standard Scoring Engine, then you will need to pass that same Score as the return value in your response. This information is used for logging (in the database), reporting, and auditing purposes. - Transaction Server logs the information returned by your Callout.
How Are Callouts Implemented
Implementation of Callouts is optional.
If you have implemented a Callout, then Transaction Server reads all configurations related to the Callout from the database and caches the information on startup. During a transaction:
- Transaction Server calls the Callout frameworkafterexecuting all pre-defined and new rules (in case of Evaluation Callout) or the standard Scoring Engine (in case of Scoring Callout.)The Callout framework is a part of Transaction Server and just like any other RA Evaluation rule, is loaded during the Server startup. It is implemented as a .dll or .so file.
- Depending on the type of Callout (EvaluationorScoring), the framework collects all the required data from Transaction Server and prepares the HTTP or HTTPS data.RA supports both one-way and two-way SSL-based connections between Transaction Server and your Callout in case of HTTPS data.
- This data is then posted (HTTP or HTTPS) to the (configured) URL of your Callout.The Callout framework now waits for a response from the Callout.If the response from your Evaluation Callout is received within a specified time-out period, then the framework parses the response and sends the result to Transaction Server.If the response is not received within the specified time-out period, then the framework returns FAILURE as the rule result and empty strings ("") for the modifier and annotation.The time-out period can be configured by using Administration Console.
- Your Callout processes the data by using custom logic.
- Your Callout then returns an appropriate response to the Callout framework, which forwards the same to Transaction Server.
- Transaction Server logs all the information returned by the framework for reporting and auditing purposes.
The following figure illustrates the interaction between Transaction Server, Callout Framework, and your Callout.

What are Rulesets
A
ruleset
is a collection of one or more configured RA rules, along with their execution order and scoring priority. Each ruleset can be different from the other in terms of:- Set of configured rules
- Score and priority for each rule in the set
- Enabling or disabling of rules in the set
- Configured parameters and data for each rule
In simple terms, a ruleset is a parent container that constitutes one or more rules. Even if you have configured a rule in RA, it will not be executed unless it belongs to a ruleset. In other words, every rule - out-of-the-box or custom - must belong to a ruleset.
As a GA, you can configure multiple global rulesets that are available to all the organizations. These rulesets can then be used by other GAs or OAs of these organizations to create new rulesets simply by "copying from" an existing ruleset. In addition, the "copied" rules within a ruleset can also be edited. This not only significantly saves the time and effort required for individually configuring each rule again for organizations, but also reduces the number of errors.
RA is shipped with an out-of-the-box global ruleset called
DEFAULT
.What Are Channels
An end user can perform a transaction in many ways. Some of these include:
- Online (Transactions that originate when the user uses a credit card or a debit card online, but the transaction is not governed by 3D Secure protocol.)
- 3D Secure (Transactions that originate when the user uses a credit card or a debit card online.)
- Online banking (Transactions that originate when the user logs into their banking site, without using a credit card.)
- Online wire transfers (Transactions that originate when the user transfers money.)
- App (Transactions that originate when the user uses a smartphone app.)
- SMS (Transactions that originate using SMS messaging.)
- ATM (Transactions that originate at an ATM machine.)
- POS (Transactions that originate at a store's or shop's point of sale.)
These different origins of transactions are referred to as
channels
in RA terminology.RA can be configured to evaluate risk for transactions coming from any of these channels. It can also be configured to evaluate transactions from each channel differently to generate a risk score. In addition, an RA rule can be evaluated across different channels to arrive at a score. This is known as
cross-channel
configuration.RA supports the channels listed in the following table.
Channel
| Description
|
DEFAULT | Transactions that are initiated using a Web browser. This may be either a computer, smart phone, tablet, or set-top box. The default channel is the Web channel. |
3D Secure | Online transactions initiated using credit card or debit card. |
ATM | Transactions initiated through ATM. ATMs are terminals primarily used as an alternate channel for availing banking services, such as account balance inquiry or cash withdrawal. |
POS | Transactions initiated at physical Point of Sale (POS). POS terminals are primarily used as channels for recording a financial payment made by the card holder to a merchant for goods or services purchased by the card holder from the merchant |
IMPS | Transactions initiated using Immediate Payment Service (IMPS), a channel-agnostic payment service. Using IMPS, bank customers can transfer money instantly within any of the IMPS-enabled member banks across India. IMPS is accessible through mobile banking, net banking, and ATM channel. IMPS can be used for funds transfer and merchant payments. It supports the following services:
|
ECOM | Ecommerce transactions received as ISO 8583 messages. |
What Is Predictive Model
Predictive Model
is RA's advanced fraud modeling capability. A pre-defined Model is not shipped with RA, but you need to build it using the historical data and then deploy it. In this way, a Model deployment is like deploying a Custom Rule, which is an additional rule and needs to be similarly created and deployed.By using the available transaction data and system data, the Model generates a score that describes the extent to which the model suspects a transaction’s genuineness. This score typically ranges from 0 through 1000, where the higher the number, the greater the possibility of fraud. RA can be configured to send different responses to your calling application based on this model score.
The score from the Predictive Model is available as a part of the system parameters (as Predictive_Score) while configuring rules on the Rules and Scoring Management page in Administration Console. This score can be used in conjunction with other data elements to arrive at a risk advice.
RA publishes an interface specification called
Predictive Model Integration Interface
, and it supports the Data Science Platform (DSP) v1.0.Model Deployment Options
- RA can connect simultaneously to one or more types of Model platforms or to one or more instances of the Model platform.
- Each organization can either have their own Model setup or share the same model setup, as long as one organization has exactly one model setup.
What Is Rules Engine
After RA collects the data (discussed in section, Understanding the Data RA Uses) for risk evaluation, it is forwarded to
Rules Engine
(a module of Transaction Server). Rules Engine executes the configured rules in the order of their priority.The Rules Engine generates an individual risk score and advice for each rule it executes and then passes it to the Scoring Engine.
What Is Scoring Engine
Scoring Engine
is a module of Transaction Server that works with Rules Engine. It accepts the input from the Rules Engine, evaluates the score of each rule in the order of priority set (by the administrator).The
risk score
generated by the Scoring Engine is an integer from 0 through 100. Scoring Engine then uses this risk score to generate the corresponding advice
and returns this advice to your application.What Is Rule Priority
RA evaluates and scores each configured and active rule in the specific order of its priority.
For example,
if the priority of a rule is set as 3, then it will be evaluated only after rules with priority 1 and 2 have been run.By default, RA assigns a priority for each out-of-the-box rule, but based on your business requirements, you can change this priority of rule scoring. The following figure is a schematic representation of RA rules and their scoring order.

How Does Risk Score Work
Based on the result of the execution of each rule that Rules Engine provides, the Scoring Engine evaluates the score of each rule in the order of priority set (by the administrator) and returns the score corresponding to the first rule that matched.
Scoring Example
Consider that you have configured these rules in the following order:
- Negative IP (say, with a score of 85)
- User Velocity (say, with a score of 70)
- High Amount Check (say with a score of 80)
- Device Velocity (say, with a score of 65)
High scores are typically assigned to rules that are more critical.
If RA determines that a transaction is coming from a risky IP address, then it returns a score of 85 (Deny), based on the first configured rule that matched. If another transaction exceeds the configured Device Velocity, then RA returns a score of 65.
The
risk score
generated by the Scoring Engine is an integer from 0 through 100. RA then uses this risk score to generate the corresponding advice
and returns this advice to your application.Scoring Matrix
The following table shows the default out-of-the-box risk score and corresponding advice matrix. You can configure these ranges according to your organization policies and requirements.
Score Value (From)
| Score Value (To)
| Advice
| Default Recommended Action
|
0 | 30 | ALLOW | Allow the transaction to proceed. |
31 | 50 | ALERT | Take an appropriate action. For example, if the user name is currently unknown, then on getting an alert you can either redirect it to a Customer Support Representative (CSR) or you can create a user in RA. |
51 | 70 | INCREASEAUTH | Perform additional authentication before proceeding any further. |
71 | 100 | DENY | Deny the transaction. |
What Does Risk Advice Mean
Based on the Risk Score generated by RA,
risk advice
can be one of the following:- ALLOW:RA returns ALLOW, if the risk score associated with the transaction is low.
- ALERT:If a user who is not registered with RA tries to log in, then ALERT is returned.
- INCREASE AUTHENTICATION:When RA detects a suspicious transaction, it flags the transaction with INCREASE AUTHENTICATION and advises the application to force the user for additional authentication.For example, when a user registered with RA attempts a transaction from a device that is not yet recognized by RA, then the user must undergo secondary authentication (such as OTP or QnA) with your application.
- DENY:RA returns the DENY advice when a high risk score is associated with the transaction.
The following figure illustrates the advices returned by RA:

How Does Rule Engine Work
The working of Rules Engine is explained with the help of the following topics:
How Are Rules Triggered
If the incoming information from a login attempt or a transaction satisfies a condition configured for a rule, then the rule fires. In RA terminology, a rule that is triggered is also referred to a "matched rule".
RA executes all configured and enabled rules in the parent ruleset. However, it scores the first matched rule and returns the risk score and advice of the rule that matched as final.
See section, "How Rules Engine Uses Rules to Calculate a Risk Score and Advice" to understand the process RA uses to arrive at the final risk score and advice.
How Rule Engine Uses Model to Calculate Model Score
RA allows for an organization-level (or tenant-level) usage of the Predictive Model through the
Model Callout
feature. The Model Callout is executed, if the Model is configured for the specified organization. It is executed after
all the system rules are executed and before
the execution of any custom rules you might have deployed. The output of the Model is made available as Predictive_Score
for the Rule Engine. This value can be used to create other rules, if required.RA expects a numerical value between 0 and 1 as the Model Score from the Model, representing the probability of the transaction being a fraudulent. Because this score is multiplied by a factor prior to making the same available to the Rule Engine for risk evaluation, the Model Score received from the Model is referred to as
Raw Model Score
. The multiplication factor is called Score Multiplication Factor
.Valid Raw Model Score:
All score output values between 0 and 1 (both inclusive)Invalid Raw Model Score:
Any score output values less than 0 or greater than 1DSP Model Score Multiplication Factor
DSP's Raw Model Score (
PREDICTIVE_SCORE
) is multiplied by a factor (generally, 1000
) prior to making the same available to the Rule Engine for risk evaluation.GDP Model Score Multiplication Factor
GDP's Raw Model Score (
MODEL_SCORE
) is multiplied by a factor (generally, 100
) prior to making the same available to the Rule Engine for risk evaluation.How it Works
When a valid Raw Model Score is received, the RA system multiplies the same by the configured Score Multiplication Factor, rounds it up to the nearest integer, and finally, presents the same as PREDICTIVE_SCORE or MODEL_SCORE to the Rule Engine for risk evaluation. The multiplied value is also persisted as PREDICTIVE_SCORE as part of the transaction audit logs.
When an invalid Raw Model Score is received, then the RA system persists a corresponding negative value. The actual received invalid value is stored in the debug log files.
If any error message or error code is received along with the Raw Model Score, then the same is logged in the Transaction Server’s debug logs. This information is not available in the database.
If for some reason, no Raw Model Score is received, then the Risk Analytics system persists a negative value.
Model Deployment Options
- RA can connect simultaneously to one or more types of Model platforms or to one or more instances of the Model platform.
- Each organization can either have their own Model setup or share the same model setup, as long as one organization has exactly one model setup.
How Rules Engine Uses Rules to Calculate a Risk Score and Advice
RA scores rules in the order of their precedence (or Scoring Priority, or Priority, in short). The evaluation result is then forwarded to another module of Transaction Server called the Scoring Engine. Between Rules Engine and Scoring Engine, the rules are run in the following two phases:
- Execution PhaseTransaction Server does a first parse of all the rules in the active ruleset. In this phase, the Server:
- Executes all the rules, including the configured Model, in the list in the order of execution priority.This execution priority is internal, and is defined by the Server.
- Generates an individual risk score and advice for each rule it executes.
- Scoring PhaseTransaction Server now does the second parse of the rules. In this phase, the Server:
- Uses the result for each rule in the first parse, and parses the rules in the ruleset based on the scoring priority.The scoring priority is configured by the Global Administrator (GA) by using the Administration Console.
- Stops the scoring at first matched rule.The term "matched rule" implies that the risk score generated for the rule in the Execution Phase was in the (default) risky range of 51-100.
- Returns the score and advice of the rule that matched as final.
Depending on when the first rule matched, the second parse may not be run completely.
State Diagrams
This section quickly discusses the states a rule and a ruleset can undergo. It covers:
States of Rules
A rule, in its lifetime, can undergo the following states:
- ProposedYou might configure a rule over a period of time by using several console sessions. These changes are reflected in theProposedcolumn in the Rules and Scoring Management page. While a rule stays in proposed state, it is not used for risk evaluation.
- ActiveWhen you configure the rule to meet your requirements, you enable it for a ruleset, migrate it to production, and refresh the server cache. When you do this, the proposed rule configuration is moved to theActivecolumn of the Rules and Scoring Management page. Only when you do this, the rule is active and used in any future risk evaluations.
- DeprecatedThis is not a formal state, but when you disable a rule from its parent ruleset, the rule is deprecated. Although the rule continues to exist in the system, it is not used in future risk evaluations.The deprecated rule can be made active any time by assigning it to a ruleset, migrating it to production, and refreshing the server cache.
States of Rulesets
A ruleset, in its lifetime, can undergo one of these states:
- AssignedIn this state, a ruleset is assigned to be the primary (or active) ruleset for an organization. You can use the Assign the Ruleset page in the Administration Console for this purpose.
- UnassignedThis is not a formal state, but when you unassign a ruleset from its organization, the ruleset is unassigned. Although the ruleset continues to exist in the system, it is not used in future risk evaluations.The deprecated ruleset can be made active any time by assigning it to an organization, migrating it to production, and refreshing the server cache.