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.
-
All steps from UX Studio Installation and Sandbox Setup Guide (from SFCC) have been completed.
-
A SFCC Development Resource: The integration and installation process includes deployment of a generic cartridge and modification of storefront code and controllers.
Kount Link Cartridge includes the following:
-
RIS HTTPS POST
-
DDC implementation within checkout process
-
Supported payment types:
-
Credit card type
-
PayPal
-
Gift certificate
-
-
ENS update to SFCC instance
-
User Defined Field (UDF) support
-
Device Data Exclusion Array (support for phone orders)
-
Multiple websites
-
Email notifications for errors, ENS, and Risk Change Events
-
API/RIS Key (instead of older certificate/key configuration)
-
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.
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 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.
-
For instructions on creating an API key, refer to How to Create an API Key for Authentication to Kount.
-
Select both RIS and API when creating the API key.
-
The API keys must remain on each server that is posting to Kount.
-
Note
API keys are specific to each environment. For example, API keys created in the test environment do not work in the production environment.
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.
The int_kount
and int_kount_sfra
cartridges are required for the integration. If you encounter any problems, email support@kount.com.
Use the kount_metadata.xml
file to create the custom System Object definitions and configure the Kount Site Preferences.
-
After signing in to SFCC Business Manager, go to Administration, and then Site Development.
-
Select Import & Export.
-
Select Upload to upload the
kount_metadata.xml
file. -
Select Choose File, and then find and select
kount_metadata.xml
. -
Select Upload. The
kount_metadata.xml
file is now listed on the Manage Import Files page. -
Go back to the Import & Export page, and then select Import.
-
Select
kount_metadata.xml
file, and then select Next. An XML Validation runs. -
Select Import.
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.
-
After signing in to SFCC Business Manager, go to Administration, and then Site Development.
-
Select Upload in the Import & Export Files section.
-
Select Choose File, and then select
kount_service.xml
file from metadata folder. -
Select Upload.
-
Select Back.
-
Select Import in the Services section.
-
Select the
kount_service.xml
, and then select Next. -
After file validation, select Next.
-
On the next page, select Merge, and then Import.
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.
-
Verify the site preferences by navigating to Merchant Tools, Site Preferences, and then Custom Preferences.
-
Select Kount to display the Custom Site Preferences page. All sandbox onboarding information needed for this page is provided by your Customer Success Manager.
-
See the Custom Site Preferences section for more information.
-
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
orstorefront_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.
The Cartridge must be assigned to the customer's website and business manager.
-
Go to Administration, then Sites, and then Manage Sites.
-
Select the desired site from the site list, and then select Settings.
-
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.
-
Select Apply.
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')}"/>
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,
Note
The display of test fields on the storefront can be turned on/off in site preferences.
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')}"/>
In the controller, controllers/CheckoutServices.js, the following library is added:
var KHash = require('int_kount/cartridge/scripts/kount/KHash');
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; });
var RISresult = Kount.preRiskCall(currentBasket, null, true); if (RISresult && RISresult.KountOrderStatus == 'DECLINED') { result = { error: true, fieldErrors: [], serverErrors: [Resource.msg('kount.DECLINED', 'kount', null)] }; }
In the same file, in the PlaceOrder handler, the following line is changed from:
var handlePaymentResult = COHelpers.handlePayments(order, order.orderNo);
To:
var handlePaymentResult = Kount.postRiskCall(COHelpers.handlePayments, order, true);
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); }
In the controller, controllers/PaymentInstruments.js, the following line is added:
custom.kount_KHash = KHash.hashPaymentToken(formInfo.cardNumber);
To configure the Event Notification Service (ENS), a Merchant URL must be set within the Agent Web Console and must be enabled in the Site Preferences in SalesForce Commerce Cloud. All events are sent to the ENS URL as an XML POST.
The cartridge does not typically require adding an IP or port to an allowlist. Communication works through port 443, which is not blocked by SalesForce Commerce Cloud. Enabling Limit Storefront
and adding approved storefront controllers to the Allowlist
prevent unauthorized access to storefront orders. To enable allowlists in SalesForce Commerce Cloud:
-
Sign in to SalesForce Commerce Cloud.
-
Go to Merchant Tools > Site Preferences > Order.
-
Select Order Access Settings.
-
Set Limit Storefront Order Access to Allowlist.
-
Add the KENS controller to the allowlist.
Note
Storefront controllers that are allowed access to storefront orders but are not on the allowlist are identified in Business Manager Alerts. All unnecessary or unsecured storefront controllers should be removed from the allowlist to prevent unauthorized access.
Refer to the following lists of IP Addresses that must be added to an allowlist 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
-
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:
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.
-
Set the ENS URL within Kount. Go to the Fraud Control tab, and then Websites.
-
Click Settings, and then click Edit. The Edit Row dialog displays.
-
Select ENS Enabled. Enter the ENS URL (unique to your merchant account) within the Merchant ENS URL.
-
Click Update Website.
A green checkmark indicates the website was successfully edited.
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
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.
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.
-
From the Fraud Control tab, select User Defined Fields.
-
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).
Note
When creating UDFs there may be a few minutes delay from the time of creation to the display within the AWC.
-
To pass information into UDFs, navigate within the DW Business Manager. Go to Site Preferences, and then Custom Preferences.
-
Select Kount, and then scroll down to the Kount UDF fields.
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.
-
Go to Administration, Site Development, and then Development Setup.
-
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.
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
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.
-
To customize the decline message, open the kount.properties folder:
int_kount/cartridge/templates/resources/kount.properties
-
Change the text of kount.DECLINED to your desired message. Message example:
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:
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 |
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:
Kount Review/Escalate
This is an example of an order that has triggered a review or escalate rule action in Kount+8/700.
Kount Approved
This is an example of an order that has not triggered a rule or was manually approved in Kount.
Kount Decline
This is an example of an order that triggered a decline rule action or was manually declined in Kount.