How to Develop Fraud Screening Plugins

How to develop fraud screening plugins using CloudBlue Commerce Fraud Screening SDK

Note: The Fraud Screening SDK provides several sample plugins located in the /var/www/pa-fraud-sdk/ directory on the Billing Application Node.

Fraud screening plugins are implemented as PHP scripts packages. An individual plugin can help CloudBlue Commerce to perform one of these functions:

Non-blacklist fraud screening operations. Using a plugin that implements this function, a provider can set some restrictions on the values of some order parameters. Such restrictions are configured on the plugin configuration screen in the CloudBlue Commerce provider control panel. When an order violates any of such restrictions, the plugin returns an error to CloudBlue Commerce.
Blacklist-related fraud screening operations. Using a plugin that implements this function, a provider can validate some order data (such as customer details, service plan details and so on) against a blacklist managed by a third-party system. When an order qualifies for blacklisting, the plugin returns an error to CloudBlue Commerce.
Validation and eligibility checks. Using a plugin that implements this function, a provider can disallow customers to create customer accounts in CloudBlue Commerce that violate some validation and eligibility

To develop a fraud screening plugin:

Choose which of the above functions the plugin will implement.
Create a plug-in package in accordance with the conventions listed in the Location and naming conventions below.
Implement the methods that will allow CloudBlue Commerce to communicate with third-party systems to perform one of the functions above. The available methods are described in Fraud Screening Methods.

Important: While developing a plugin, after you make changes to the set of plugin configuration parameters, set of account attributes, blacklist schema or definitions of any other entities to be registered in Billing, make sure you increase the plugin version number. Otherwise, Billing will not recognize the changes when you attempt to overwrite the previous version of the plugin.

Fraud screening solution architecture

All plugins are available to CloudBlue Commerce through a pre-configured Apache virtual host. Within this virtual host a single /index.php script receives HTTP requests from CloudBlue Commerce and dispatches them to a some plugin. The plugin passes an array of parameters to an external system or processes the request internally and returns an array with the operation result to CloudBlue Commerce. See the diagram below.

Location and naming conventions

When developing a fraud screening plugin, follow these location and naming conventions:

Each plugin is deployed in its own directory in the document root directory on the Fraud Screening SDK runtime node. The document root path is /var/www/pa-fraud-sdk.
Each plugin name must be unique, containing only letters and numbers, starting with a letter.
The directory where the plugin is located must have the same name as the plugin script name. For example, the path to the IPBlacklist plugin must be $(DOCUMENT_ROOT)/IPBlacklist/IPBlacklist.php.
The directory of the plugin may contain an internationalization directory $(PLUGIN_NAME)/i18n that contains a set of files with language specific strings (case-sensitive):
- The file name must be: <two-letter language code>.string
- The file must contain all language-specific strings for the given language. Each string must start from the new line.
- The structure of each string must be: "<key>" "<translation>".
Any other files used by the plugin can be placed into the plugin folder.

Important limitations

Depending on their implementation, Validation and Eligibility plugins can return the values of customer classes to be assigned to new customers that place an order. Use this capability carefully to avoid problems similar to this one:

Problem scenario example: When placing an order, a customer enters a promotion code received from a sales agent. The promotion code tells the system that the customer belongs to the customer class “Online customer”. The system validates the customer data with a Validation and Eligibility plugin, which returns the customer class “Traditional business customer". Since the customer is assigned two different customer classes, the system returns a validation and eligibility error.
Solution: If you implement a Validation and Eligibility plugin so that it can return customer class values (depending on the data new customers submit), make sure that the customer classes assigned to service plans or promotions are not in conflict with the customer classes returned by the Validation and Eligibility plugin. To do so, check and adjust customer class configurations for the Validation and Eligibility plugin, service plans, and promotions.

Plugin implementation examples

You can use the plugin implementation samples available in the /samples sub-directory in the Fraud Screening SDK directory on the Billing application node. To install the sample plugins to your CloudBlue Commerce system, use the demo plugin installation script.

Default implementation of fraud screening methods (included in the examples above)

Each optional method has a default implementation, which is automatically implemented by the SDK runtime for those plugins in which the method is not implemented.

For information on the default implementation for each optional method, please see the plugin implementation examples in the /samples sub-directory in the Fraud Screening SDK directory on the Billing application node.

Methods needed for different plugin types

How to Develop Fraud Screening Plugins