Quick Links

How to Implement SalesForce Commerce Cloud

The Kount SalesForce Commerce Cloud (SFCC) cartridge provides rapid integration for SFCC implementations. The Kount cartridge is a self-contained cartridge that can easily integrate into any project. This cartridge can be configured in the Business Manager and contains all elements necessary to perform a successful best practices implementation of Kount. Kount aggregates and evaluates data from three primary sources, the Device Data Collector (DDC), the Risk Inquiry Service (RIS), and the Kount Persona technology. From these three sources Kount provides a risk score and a response based upon merchant administered rules.

The DDC gathers information from a customer’s device and sends it to Kount. This passive analysis obfuscates Kount interaction with the customer and does not affect the customer’s purchasing experience. The RIS evaluates the data provided by the DDC and the order-form data submitted to the merchant from the customer to create a fraud score. Customer-specified rules are assessed for each transaction during this evaluation process.

The Kount Persona is comprised of linked data points across the all Kount customers, which provide behavioral analytics related to a transaction.

The Kount SFCC Link Cartridge is maintained and supported by a third-party development firm. If additional Link Cartridges or customizations have been added to your instance of SFCC, conflicts might occur and could result in additional support and/or maintenance fees outside the Kount standard integration.

Requirements

  1. All steps from UX Studio Installation and Sandbox Setup Guide (from SFCC) have been completed.

  2. A SFCC Development Resource: The integration and installation process includes deployment of a generic cartridge and modification of storefront code and controllers.

Functional Overview

Kount Link Cartridge includes the following:

  1. RIS HTTPS POST

  2. DDC implementation within checkout process

  3. Supported payment types:

    • Credit card type

    • PayPal

    • Gift certificate

  4. ENS update to SFCC instance

  5. User Defined Field (UDF) support

  6. Device Data Exclusion Array (support for phone orders)

  7. Multiple websites

  8. Email notifications for errors, ENS, and Risk Change Events

  9. API/RIS Key (instead of older certificate/key configuration)

Limitations/Constraints

  • No AVS or CVV information are passed

  • Only listed payment methods are sent to Kount

  • For orders made with a credit card saved in the customer profile before cartridge integration, an empty payment token is sent to Kount.

Privacy/Payment

Kount supports different payment types and depends on the customer payment type (payment tokens are required). If the chosen payment method is not supported by Kount, then a value of NONE is passed.

The integration uses customer profile data, and then transfers it to Kount. Hashed credit card data is sent to Kount system. The following credit card data is sent:

  • Hashed credit card number (using KHASH — Salted Irreversible Hash; PCI Level 1 Compliant)

  • Customer name on order

  • Credit card type

Kount Environments

Kount has separate environments for test and production. The initial integration must take place in the Kount test environment before the production environment. Boarding documents containing the information for the test environment are contained in the welcome email provided to a customer when they begin the onboarding process with Kount.

The test environment is not engineered to support load testing; it is designed primarily to verify connectivity and proper data submission. Many features such as order linking, scoring, device location, and persona related information are disabled or limited in the test environment.

  • Test credit cards can be passed into the test environment but will fail in the production environment.

  • HTTPS over port 443 is required for submission and receipt of data in both the test and production environments.

  • API Keys are required to authenticate to Kount. Each environment requires a separate API key.

Note

API keys are specific to each environment. For example, API keys created in the test environment do not work in the production environment.

Integration Certification

Upon verification that the correct data is being passed for both the DDC and RIS, a Certification Letter is issued along with an additional onboarding document that provides the production environment information.

Any customized data created in the Kount test environment must be re-created in the production environment, which includes, users, rules, site IDs, user defined fields, and API keys.

The test environment will continue to be available to the customer for testing purposes, but must not be used with production data traffic.

Implementation Setup

The int_kount and int_kount_sfra cartridges are required for the integration. If you encounter any problems, email support@kount.com.

Configuration

The configuration steps are:

  1. Import the kount_metadata.xml file

  2. Create services in the DW Business Manager

  3. Implement Kount Site preferences

  4. Create an API key in the Kount Admin section

  5. Assign the Cartridge to a website

  6. Configure ENS (Optional)

Step 1: Site Import

Use the kount_metadata.xml file to create the custom System Object definitions and configure the Kount Site Preferences.

  1. After signing in to SFCC Business Manager, go to Administration, and then Site Development.

  2. Select Import & Export.

  3. Select Upload to upload the kount_metadata.xml file.

    sf5.png
  4. Select Choose File, and then find and select kount_metadata.xml.

    sf6.png
  5. Select Upload. The kount_metadata.xml file is now listed on the Manage Import Files page.

  6. Go back to the Import & Export page, and then select Import.

    sf8.png
  7. Select kount_metadata.xml file, and then select Next. An XML Validation runs.

    sf9.png
  8. Select Import.

    sf10.png

    After the import has finished, a Success status displays.

    Note

    If the Success status does not display, check the DW Sandbox Setup (Site Genesis), and then attempt the import again.

Step 2: Import Service

  1. After signing in to SFCC Business Manager, go to Administration, and then Site Development.

  2. Select Upload in the Import & Export Files section.

    sf11.png
  3. Select Choose File, and then select kount_service.xml file from metadata folder.

  4. Select Upload.

  5. Select Back.

  6. Select Import in the Services section.

    sf13.png
  7. Select the kount_service.xml, and then select Next.

    sf14.png
  8. After file validation, select Next.

  9. On the next page, select Merge, and then Import.

    sf15.png

Step 3: Kount Site Preferences

Kount site preferences must be added to the fields on this page. The script file displays the default values, but does not populate the fields automatically.

  1. Verify the site preferences by navigating to Merchant Tools, Site Preferences, and then Custom Preferences.

  2. Select Kount to display the Custom Site Preferences page. All sandbox onboarding information needed for this page is provided by your Customer Success Manager.

  3. See the Custom Site Preferences section for more information.

Custom Site Preferences

  • Kount API Key: This is where the API/RIS key is entered. Refer to Kount Environments if you have questions about API/RIS key creation.

    Note

    The API key requires RIS permissions to function properly.

  • Enable Event Notification Service: Toggles on or off (yes or no in the drop-down menu). The ENS service communicates status changes in Kount to SFCC and updates them within the order. Refer to Step 7 for additional steps to enable and configure ENS.

  • Kount ENS Email list: If you want email notifications to be sent when ENS events are posted, enter an email address in this textbox, and then select Add.

  • Array of Internal IP Addresses to exclude from Data Collection: This text field is designed for internal IP Addresses that ignore device data. For instance, if your organization accepts phone orders, you can enter the internal IP Addresses of the agents who accept those orders so their devices are not attached to the independent orders being taken over the phone.

  • Website ID: Typically default, although website values can be passed. The corresponding website values must be created inside the AWC. To do so, navigate to the Fraud Control tab, and then Websites.

  • Merchant ID: The MID value is provided by your Customer Success Manager.

    Note: Kount does not provide email notifications for any events. The SFCC Link Cartridge has the ability to provide email notifications for various features within SFCC, this is not a feature provided by Kount but rather SFCC.

  • Kount ERROR Notification Email: A list of email addresses that you would like any errors or warnings sent to that have occurred within SFCC concerning the Kount Link Cartridge. See the Error Logging and Notifications section of this document for more information about the log files.

The next six fields after Kount ERROR Notification Email are various ENS email notifications. If any of these events are triggered, an email is distributed to all emails listed in email field in the Kount ENS Email List.

After the ENS email notification section, continue with Kount UDF fields.

  • Kount UDF fields: Can be established in the field. There are additional steps to enabling and configuring UDF values please refer to Managing User Defined Fields.

  • Enable Kount: Enables the Kount service to run against orders being passed into the environment.

  • Authorization type: Kount allows two different order workflow types as Pre-Authorization and Post-Authorization.

  • Mode: Test mode for test environment production for production environment.

  • Core cartridge (controllers): Kount uses your storefront controller cartridge, fill out this field with the name of this cartridge. For example, this cartridge can be named app_storefront_controllers or storefront_controllers. You find the name on the Cartridges input page (Administration > Sites > Manage Sites > NAME_OF_YOUR_SITE Settings > Cartridges input).

    Example: app_storefront_controllers

  • Enable Test Verifications: For testing purposes you can turn on or turn off the Enable Test Verifications field, which is displayed in the storefront on the summary page (in the checkout process).

  • Hash Salt Key: The HASH Salt Key is used for hashing credit card numbers and is provided by an email from Kount.

Step 4: Assign Cartridge to Site

The Cartridge must be assigned to the customer's website and business manager.

  1. Go to Administration, then Sites, and then Manage Sites.

  2. Select the desired site from the site list, and then select Settings.

  3. Add the following code to the Cartridges list:

    int_kount_sfra:int_kount:

    Note

    Make sure to include the colon after kount in the previous code example.

  4. Select Apply.

Step 5: Setup validation services

If you are using address or credit card validation services, save the response from the used service to the basket custom attributes:

  • Address Verification System Street — basket.custom.kount_AVST

  • Address Verification System Zip Code — basket.custom.kount_AVSZ

  • Card Verification Value — basket.custom.kount_CVVR

Use the below values for the response:

Value

Description

X

Unsupported

M

Match

N

Not a Match

For testing purposesonly, there is a modified template: int_kount_sfra/cartridge/templates/default/checkout/checkout.isml, with line:

  <isinclude url="${URLUtils.url('K-ExampleVerification')}"/>
sf18.png

For the same test purposes, the client JavaScript file is also updated:

int_kount_sfra/cartridge/client/default/js/checkout/checkout.js

In section stage === 'placeOrder' are added lines:

  var kountExampleVerification = $('.kount-selector').serialize();
  data: kountExampleVerification,
sf19.png

Note

The display of test fields on the storefront can be turned on/off in site preferences.

Step 6: The SFRA version does not need Storefront modifications

The following upgrades are described in case of conflict with other cartridges.

In the template, checkout/billing/paymentOptions.isml, the following line is added:

<isinclude url="${URLUtils.url('K-DataCollector')}"/>
sf20.png

In the controller, controllers/CheckoutServices.js, the following library is added:

var KHash = require('int_kount/cartridge/scripts/kount/KHash');
sf21.png

In the same file, in the SubmitPayment handler, the following lines are added:

wrap(function() {
    currentBasket.custom.kount_KHash = paymentInstrument.raw.custom.kount_KHash || null;
});
sf22.png
var RISresult = Kount.preRiskCall(currentBasket, null, true);
if (RISresult && RISresult.KountOrderStatus == 'DECLINED') {
    result = {
        error: true,
        fieldErrors: [],
        serverErrors: [Resource.msg('kount.DECLINED', 'kount', null)]
    };
}
sf23.png

In the same file, in the PlaceOrder handler, the following line is changed from:

var handlePaymentResult = COHelpers.handlePayments(order, order.orderNo);
sf24.png

To:

var handlePaymentResult = Kount.postRiskCall(COHelpers.handlePayments, order, true);
sf25.png

In the same file, in the PlaceOrder handler, the following line is changed from:

sendConfirmationEmail(order, req.locale.id);

To:

if(!Kount._isKountEnabled() || handlePaymentResult && handlePaymentResult.KountOrderStatus == "APPROVED") {
    COHelpers.sendConfirmationEmail(order, req.locale.id);
}
sf26.png

In the controller, controllers/PaymentInstruments.js, the following line is added:

custom.kount_KHash = KHash.hashPaymentToken(formInfo.cardNumber);
sf27.png

Step 7: Configure the Event Notification Service (optional)

To configure the Event Notification Service (ENS), a Merchant URL must be set within the Kount AWC and must be enabled within the Site Preferences in SFCC (use this link for the location of this setting). All events are sent to the ENS URL as an XML post(s).

The cartridge does not typically require adding IP or port to whitelist. Communication works through port 443 which is not blocked by SFCC.

If needed, refer to the following list of IP Addresses that need to be whitelisted on your server in order to receive the XML posts from Kount:

Sandbox

  • 208.75.115.254

  • 208.75.112.254

Production

  • 208.75.115.253

  • 208.75.112.253

  • 209.81.12.251

Configuring ENS

  1. Identify your unique Merchant URL. The default value might be different if the customer is using a language other than English.

    Example of an ENS URL:

    sf28.png

    The rest of the URL consists of static values.

    Note

    There is a difference between the SFCC and SFRA URLs. The SFCC URL ends with /K_ENS-EventClassifications and the SFRA URL ends with /KENS-EventClassifications.

  2. Set the ENS URL within Kount. Go to the Fraud Control tab, and then Websites.

  3. Click Settings, and then click Edit. The Edit Row dialog displays.

    sf29.png
  4. Select ENS Enabled. Enter the ENS URL (unique to your merchant account) within the Merchant ENS URL.

  5. Click Update Website.

    sf30.png

    A green checkmark indicates the website was successfully edited.

External Interfaces (communication between Kount and SFCC)

The cartridge uses ENS to synchronize with Kount.

Callback Controllers:

Notifications from Kount are sent to the cartridge as a series of events formatted in XML. Handlers for these events are implemented as controllers. K_ENS-EventClassifications is an event sorter. It uses the configuration described in Step 6.

  • The event sorter determining classification of the event is: K_ENS-EventClassifications

  • The different event handlers are: WorkflowStatusEdit, WorkflowReevaluate, RiskChangeScor, RiskChangeReply, RiskChangeVelo, RiskChangeVmax, RiskChangeGeox, RiskChangeNetw, RiskChangeReas

User Defined Fields Setup and Configuration

The syntax must be formatted to match the values shown in the graphic in order to map correctly within Kount. The System Object Names within SFCC that can be accessed with UDFs are as follows:

Object Name

Label Name

Example Use

Order

order

Date|order.date

Shipping Address

shippingaddress

State|shippingaddress.state

Billing Address

billingaddress

City|billingaddress.city

*Customer Profile

profile

DOB|profile.dob

Note

*Customer Profile Information is exported in case the order was placed by a registered customer. System Object Definitions and their attributes can be found on in the System Object Definitions (Administration > Site Development > System Object Definitions). The Amount UDF Type is not supported in SFCC at this time. If you want to support custom objects within SFCC, refer to Modifying UDF map within SFCC.

Configuration of User Defined Fields within Kount (optional)

Note

This is an optional portion of the integration.

Kount provides a way for merchants to include additional information related to their business that may not be a standard field in Kount by creating UDFs. UDFs should be first setup in the Kount admin panel.

  1. From the Fraud Control tab, select User Defined Fields.

  2. UDF field has type Number by default. In order to change the type, select the appropriate value using the Type selection menu (alphanumeric is the only value that can contribute to the VIP List).

    sf31.png
    sf32.png

    Note

    When creating UDFs there may be a few minutes delay from the time of creation to the display within the AWC.

UDF Settings within SFCC Custom Preferences

  1. To pass information into UDFs, navigate within the DW Business Manager. Go to Site Preferences, and then Custom Preferences.

  2. Select Kount, and then scroll down to the Kount UDF fields.

    sf33.png
    sf34.png

Modifying UDF Map within SFCC

  1. To support other SFCC objects, additional mapping must be done by adding getUDFObjectMap in script LibKount.js.

  2. Add the following new object to the map:

    UDFMap.put(<label of the object>, {
          "meta" : <DW object>.describe(),
          "object" : <DW object>
    });

Logging

To facilitate troubleshooting ensure that logging is enabled in the SFCC Link Cartridge. The Kount Link Cartridge will not interfere with default checkout flow of a site. If an error occurs within the Kount Link Cartridge or if the Kount Service cannot be reached, errors are written into separate log files.

Logs are located in Development Setup.

  1. Go to Administration, Site Development, and then Development Setup.

  2. Go to the Log Files section. The log file naming convention is: custom-Kount-blade0-4-appserver-<date stamp>.log

Notifications can be enabled to deliver email messages to specific addresses, if an error does occur.

sf1.png

Example of the email body for a notification email:

Error during execution

Site Name - Kount

Errors description - Kount method/script - PostRiskInqueryService.ds;ERROR - java.net.SocketTimeoutException: Read timed out

SFCC Workflow

Within the SFCC workflow, if an order is declined with a Kount rule, there is a generic decline message that displays on the checkout page when the customer is attempting to place their order. The displayed message can be customized within SFCC.

  1. To customize the decline message, open the kount.properties folder: int_kount/cartridge/templates/resources/kount.properties

  2. Change the text of kount.DECLINED to your desired message. Message example:

    sf3.png

Error Logging and Notifications

The Kount Link Cartridge does not interfere with default checkout flow of a site. If an error occurs within the Kount Link Cartridge or if the Kount Service cannot be reached, errors are written into separate log files.

Example of the log file naming convention:

custom-Kount-blade0-4-appserver-<date stamp>.log

Notifications can also be enabled to deliver email messages to specific addresses if an error were to occur. Refer to Step 3: Kount Site Preferences to set notification emails.

Example of the email body for a Notification Email:

sfcc.png

Error descriptions

Error Message

Possible Causes/Solutions

Kount method|script - Update Orders; ERROR - KOUNT: UpdateCustomAttribute.js: Order not found

1. Check API callback link at the Kount - Fraud Control - Websites

2. Make sure that orders in Kount Dashboard exist in BM

Kount method|script - EventClassifications; ERROR - KOUNT: K_ENS.js: Error when parsing ENS xml

Ensure that you using latest version of Kount cartridge

Kount method|script - PostRISRequest; ERROR - The service is not enabled

Ensure that your Kount Service is enabled (BM - Administration - Operations - Services)

Kount method|script - Update Orders; ERROR - KOUNT: UpdateOrder.ds: kount_REPLY custom field was not saved

Check your error logs for details

SalesForce Commerce Cloud Order Post-Authorization Workflow

The SFCC Workflow Diagram provides an overview of how a transaction flows through SFCC when the Kount SFCC Link Cartridge is enabled. The following provides examples of the workflow within a default installation of the Kount Link Cartridge and the expected workflow diagram:

sf35.png

Kount Review/Escalate

This is an example of an order that has triggered a review or escalate rule action in Kount+8/700.

sf36.png
sf37.png

Kount Approved

This is an example of an order that has not triggered a rule or was manually approved in Kount.

sf38.png
sf39.png

Kount Decline

This is an example of an order that triggered a decline rule action or was manually declined in Kount.

sf40.png
sf41.png
Was this article helpful?
1 out of 1 found this helpful