This Implementation Guide describes how to integrate the NoFraud eCommerce Fraud Prevention into the Salesforce Commerce Cloud reference application Store Front Reference Architecture (SFRA) v 5.1.0

The int_nofraud_sfra component allows extending Salesforce Commerce Cloud flows to support fraud prevention mechanisms by integrating to NoFraud eCommerce Fraud Prevention via NoFraud Application Programming Interface (API) calls. For additional information contact NoFraud here.

Integration to NoFraud consists of deploying and configuring of the int_nofraud_sfra cartridge. There are no modifications needed for the core cartridge. An optional feature of NoFraud, Device Detection, can be achieved by the SFRA approach of overriding the appropriate checkout template file.

Use Cases

Fraud Detection:

Fraud detection happens as a part of the Place order phase during checkout.

NoFraud integration uses standard SFRA app.fraud.detection hook to detect a potentially fraudulent activity after the payment.

Additionally, it hooks into the standard app.post.auth post-authorization step in order to access additional Order information, namely the Order Id. Order Id is stored into session custom privacy attributes to be read later in the flow.

Scripts that are executed for these hooks are defined as follows in hooks.json file:

{

    "hooks": [

        {

            "name": "app.fraud.detection",

            "script": "./hooks/nofraud.js"

        },

        {

            "name": "app.post.auth",

            "script": "./hooks/postAuthorizationHandling.js"

        }

    ]

}

Relevant data is captured during these 2 steps and then sent to NoFraud for processing synchronously. The following sequence diagram shows the general flow performed during checkout which is enabled by integrating to NoFraud.

NoFraud Decision Processing:

When the NoFraud decision is received, int_nofraud_sfra script will update the order with following custom attributes:

• custom.noFraudOrderId is populated with NoFraud transaction id (example: 16f235a0-e4a3-529c-9b83-bd15fe722110)
• custom.noFraudDecision is populated with the decision (one of pass/fail/review)
• custom.noFraudNumberOfRetries is set to 0

In case of NoFraud decision “pass”, Place Order continues with execution normally.

In case of NoFraud decision “review”, Place Order continues with execution normally, but the Order will be NOT CONFIRMED. Orders with a “review” decision will be periodically checked for the review result, as described in subsequent sections.

In case of NoFraud decision “fail”, Place Order will stop, the order will be canceled and the shopper will be presented with an error message. Error code returned, in this case, will be “nofraudfailed”.

Text of the error message can be customized and localized for the code nofraudfailed (error resource bundle message message.error.nofraudfailed).

Updating Fraud Detection Response After Review:

Any Order for which NoFraud returns a decision “review” will be periodically checked for a new decision. Checking for a decision is done with a scheduled job. It is recommended that the period for the job is configured for not less than one hour.

Job step type is defined as a custom script-module-step with Id “custom.NoFraudRetryStepType”, which executes the execute() method of /cartridge/scripts/jobs/noFraudRetry.js, as defined by steptypes.json file in the cartridge.

Each time NoFraud is queried for updates to transactions, custom attribute Order.custom.noFraudNumberOfRetries is incremented. A maximum number of retries per Order can be configured with the NO_FRAUD_Maximum_Retries configuration parameter. 

Limitations & Constraints

Multiple Shipping Addresses:

• If multiple shipping addresses are used, only one shipping address will be sent to NoFraud (current “default shipping address”).

Multiple Payment Instruments:

• If multiple payment instruments are used in an Order, only one payment instrument information will be sent to NoFraud, based on the following logic:

  • If at least one Credit Card is used, NoFraud will receive information of the Credit Card being charged with the highest amount
  • Otherwise, NoFraud will receive information of the payment instrument being charged with the highest amount

Compatibility

Integration cartridge has been tested with:

• SFRA 5.1.0
• SFRA 5.0.1

Integration has been tested with compatibility mode:

• 21.2
• 19.10

Privacy & Payment

In order to make a more informed fraud detection decision, the following customer and credit card data is being accessed and sent to NoFraud, when available:

Implementation Steps

NoFraud Custom Attributes

Order Custom Attributes:

The following are custom attributes introduced on the Order object:

Attribute Group: NO_FRAUD

Attributes:

Site References:

The following are custom site preferences introduced for configuration purposes:

Attribute Group: NO_FRAUD

Attributes:

Configuration

Metadata Upload:

Upload and import metadata from the metadata folder:

• Go to Business Manager > Administration > Site Development > Site Import & Export
• Import the metadata.zip file provided in the download cartridge metadata folder:
  • Upload the metadata.zip file
  • Select the uploaded file and select Import

NoFraud Custom Preferences:

To configure NoFraud custom preferences, go to

• Merchant Tools > Site Preferences > Custom Preferences > NO_FRAUD

The following preferences need to be configured:

Disabling the Cartridge Functionality:

By setting the NO_FRAUD_Disabled to true, you have an option to disable int_nofraud_sfra cartridge functionality without removing it from the cartridge path. Specifically, when NO_FRAUD_Disabled is set to 'Yes', hooks defined in hooks.json file will not be processed, i.e., the fraud detection hook will always return the status: “success”.

Credential Configuration:

Use the following setting do configure the token needed to access NoFraud API. Please contact NoFraud for your NoFraud token.

Go to:

• Administration > Operations > Services
• Select the Credential tab
• Select nofraud-service-credentials
• URL for production is https://api.nofraud.com https://portal.nofraud.com/users/sign_up
• Fill in your NoFraud token in the password field
• Leave the User field empty

NoFraudRetry Job Configuration:

By default, the NoFraudRetry job is not enabled. Please reconfigure the job to your desired interval, and enable it, by going to:

• Administration > Operations > Jobs > NoFraudRetry

Custom Code

Enriching NoFraud Data with Device Information:

In order to enrich NoFraud requests with the device information of the customer, a Device JavaScript file must be included in the Checkout template templates/default/checkout/checkout.isml.

If you want to include this Device Information, please modify the current active checkout.isml. Follow these steps:

1. At the start of checkout.isml there should be a section with JavaScript files being imported, similar to this (actual content may vary based on other cartridges used):

Old section:

    <isscript>

        var assets = require('*/cartridge/scripts/assets.js');

        assets.addJs('/js/checkout.js');

        assets.addCss('/css/checkout/checkout.css');

    </isscript>

2. Modify this section in the new file to now contain the Device JavaScript, in the following way (by adding one line):

New section:

    <isscript>

        var assets = require('*/cartridge/scripts/assets.js');

        assets.addJs('/js/checkout.js');

        assets.addCss('/css/checkout/checkout.css');

        assets.addJs('https://services.nofraud.com/js/xxxxx/customer_code.js');

    </isscript>

Enriching NoFraud Requests with AVS & CVV Result Codes:

NoFraud fraud detection benefits greatly from the presence of AVS and CVV result codes. If you wish to provide AVS and/or CVV results code to NoFraud fraud detection processing, you can optionally choose to modify the existing payment processor scripts. The location of the added script code depends on the payment processor used. AVS and CVV result codes can usually be found in the response from the payment processor.

Once you locate the script code that has access to the response transaction containing AVS or CVV result codes, you may choose to use the following code:

var nfInput = require('*/cartridge/scripts/nofraud/input/extInput');

// modify parameters to your needs
nfInput.enrichWithAvsAndCvvResponse('DEFAULT', response.avsResponseCode, response.cvvResponseCode);

External Interfaces

The following describes the external NoFraud Interfaces used, with request and response examples. More detailed documentation on NoFraud interfaces can be viewed in our Developer Documentation at: https://portal.nofraud.com/pages/developer-documentation.

Examples of a Fraud Detection Request to NoFraud:

HTTP POST with Content-Type: application/json

{

    "customerIP": "111.222.111.222",

    "nfToken": "NF_...",

    "amount": "4374.28",

    "currencyCode": "USD",

    "shippingAmount": "43.04",

    "shippingMethod": "Ground",

    "gatewayName": "DEFAULT",

    "avsResultCode": "U",

    "cvvResultCode": "U",

    "cavvResultCode": "U",

    "merchant": {

        "name": "Test Merchant",

        "website": "store.example.com",

        "email": "merchant@example.com",

        "productType": "Goods"

    },

    "order": {

        "invoiceNumber": "00000239"

    },

    "shipTo": {

        "firstName": "John",

        "lastName": "Smith",

        "address": "Street 5",

        "city": "New York",

        "state": "NY",

        "zip": "10001",

        "country": "US"

    },

    "lineItems": [

        {

            "sku": "pioneer-pdp-6010fdM",

            "name": "Pioneer 60\" KURO Plasma High Definition Television",

            "quantity": 1,

            "price": 4124.99

        }

    ],

    "customer": {

        "id": "bcd…",

        "lastSignIn": "12/09/2020",

        "email": "email@example.com"

    },

    "payment": {

        "method": "CREDIT_CARD",

        "creditCard": {

            "last4": "1111",

            "cardType": "Visa",

            "bin": "411111",

            "expirationDate": "07-27"

        }

    },

    "billTo": {

        "firstName": "John",

        "lastName": "Smith",

        "address": "Street 5",

        "city": "New York",

        "state": "NY",

        "zip": "10001",

        "phoneNumber": "9234567896",

        "country": "US"

    }

}

Examples of NoFraud Direct API Responses:

• In case of decision “Pass”:

  {
  
    "id": "16f235a0-e4a3-529c-9b83-bd15fe722110",
  
    "decision": "pass"
  
  }

   

• In case of decision “Review”:

  {
  
    "id": "16f235a0-e4a3-529c-9b83-bd15fe722111",
  
    "decision": "review"
  
  }

   

• In case of decision “Fail”:

  {
  
    "id": "16f235a0-e4a3-529c-9b83-bd15fe722112",
  
    "decision": "fail",
  
    "message": "Declined"
  
  }

   

Get Current Transaction Status:

For periodic (scheduled) queries to the current status of transactions in the “Review” state, send HTTP GET with query by NoFraud ID to https://api.nofraud.com/status_by_url/:nf_token/:id is used.

Testing

Basic Testing

To perform a basic test to confirm if everything is configured properly, perform the following test:

NoFraud Pass Test:

1. Perform a test purchase. For the customer's email, use pass@nofraud.com – this will ensure the test NoFraud service returns a “Pass” decision.
2. Expected results: The order should process successfully.
3. Find the submitted order in Business Manager at Merchant Tools > Ordering > Order
4. Observe the Attributes for the Order. It should contain values similar to the following example:
   
5. Login to the NoFraud portal transaction dashboard and your transaction should be visible:
   

NoFraud Review Test:

1. Perform another test purchase. For the customer's email, use review@nofraud.com – this will ensure the test NoFraud service returns the “Review” decision.
2. Expected results: The order should process successfully.
3. Find the submitted order in Business Manager at Merchant Tools > Ordering > Order
4. Observe the Attributes for the Order. It should contain values similar to the following example:
   
5. Login to the NoFraud portal transaction dashboard and your transaction should be visible:
   
6. Open the Transaction and mark it as “Passed” by selecting Pass:
   
7. Back in Business Manager, manually execute the NoFraudRetry job to check if the job is configured correctly:
   1. Go to Administration > Operations > Jobs > NoFraudRetry
   2. Choose “Run Now”
   3. Under the “Schedule and History” tab, verify that the Job executed successfully with the OK status:
      
8. Check the same order now in Business Manager at Merchant Tools > Ordering > Order, making sure that the transaction is now marked as a “Pass” decision, and the order is confirmed.
   

NoFraud Fail Test:

1. Perform another test purchase. For the customer's email, use fail@nofraud.com – this will ensure the NoFraud testing service returns a “Fail” decision.
2. Expected outcome: The order should NOT process successfully and the customer should be presented with a screen similar to the following:
   
3. Find the submitted order in Business Manager at Merchant Tools > Ordering > Order
4. Confirm that the order status is Failed:
   
5. Observe the order Attributes and it should contain values similar to the following example:
   
6. Login to the transaction dashboard in the NoFraud portal and your transaction should be visible:
   

Automated Testing:

The Cartridge contains unit, integration, and function tests included in the repository. Please use instructions described in the test/unit/README.md, test/integration/README.md, and test/acceptance/README.md files in the repository to configure and run automated tests.

Operations & Maintenance

Logs:

This integration introduces a new custom log custom-nofraud-*.log. To enable it, first add a new log category:

• Go to Administration > Operations > Custom Log Settings
• Enter a new log Category nofraud at DEBUG level
• Press Add and hit Save

Data Storage:

The NoFraud integration cartridge does not store any data outside the standard Order custom attributes.

Availability, Failover, and Recovery Process:

NoFraud has redundancy built into the system through running in multiple regions and having multiple availability zones and has historically been able to achieve >99.99% availability.

Customers can report issues to NoFraud via the status page or by contacting Support. We will update the status page when updates & fixes are deployed, and your customers also can report issues to NoFraud as described above. 

System Behavior When Errors Occur:

In cases where NoFraud was unavailable at the time of a transaction, or there was an error in the processing of input data on our side, the order will proceed as if NoFraud returned a “Review” response - i.e. the order will be in the “Not Confirmed" status.

In case of NoFraud errors, there will be no visible impact to the customer's checkout experience on your storefront, and your website will continue to function as normal.

The value written to an order affected by a NoFraud outage (or errors) will have custom attribute noFraudDecision set to “error”. The NoFraud request will not be retried.

Integration Notes

• Roles: This integration introduces no new Salesforce Commerce Cloud roles.

• Business Manager: This integration introduces no new Business Manager UI elements.

• Business Manager: All NoFraud-related data is stored in the custom attribute group on the standard Order UI.

• Business Manager: A single job, NoFraudRetry, is set up, as described previously.

• Storefront Functionality: This integration introduces no new Storefront Functionality.