How to Develop Fraud Screening Plug-ins

How to develop fraud screening plug-ins using CloudBlue Commerce Fraud Screening SDK

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

Fraud screening plug-ins are implemented as PHP scripts packages. An individual plug-in can help CloudBlue Commerce to perform one of these functions:

Non-blacklist fraud screening operations. Using a plug-in that implements this function, a provider can set some restrictions on the values of some order parameters. Such restrictions are configured on the plug-in configuration screen in the CloudBlue Commerce provider control panel. When an order violates any of such restrictions, the plug-in returns an error to CloudBlue Commerce.
Blacklist-related fraud screening operations. Using a plug-in 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 plug-in returns an error to CloudBlue Commerce.
Validation and eligibility checks. Using a plug-in 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 plug-in:

Choose which of the above functions the plug-in 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 plug-in, after you make changes to the set of plug-in configuration parameters, set of account attributes, blacklist schema or definitions of any other entities to be registered in Billing, make sure you increase the plug-in's version number. Otherwise, Billing will not recognize the changes when you attempt to overwrite the previous version of the plug-in.

Fraud screening solution architecture

All plug-ins are available to CloudBlue Commerce via 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 plug-in. The plug-in 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 plug-in, follow these location and naming conventions:

Each plug-in 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 plug-in name must be unique, containing only letters and numbers, starting with a letter.
The directory where the plug-in is located must have the same name as the plug-in's script name. For example, the path to the IPBlacklist plug-in must be $(DOCUMENT_ROOT)/IPBlacklist/IPBlacklist.php.
The directory of the plug-in 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 plug-in can be placed into the plug-in's folder.

Important limitations

Depending on their implementation, Validation and Eligibility plug-ins can return the values of customer classes to be assigned to new customers that place orders in the CloudBlue Commerce Online Store. Use this capability carefully to avoid problems similar to this one:

Problem scenario example: When placing an order from the online store, 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 plug-in, 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 plug-in so that it can return customer class values (depending on the data new customers submit in the Online Store), 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 plug-in. To do so, check and adjust customer class configurations for the Validation and Eligibility plug-in, service plans, and promotions.

Plug-in implementation examples

You can use the plug-in implementation samples available in the /samples sub-directory in the Fraud Screening SDK directory on the Billing application node. To install the sample plug-ins to your CloudBlue Commerce system, please use the demo plug-in 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 plug-ins in which the method is not implemented.

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

Methods needed for different plug-in types

How to Develop Fraud Screening Plug-ins