Using Kount with Gateway.js (Payment API)

Table of Contents

1. Overview
2. Integrating Gateway.js & Kount
3. Passing the Session ID to the Payment API
4. Session ID Behaviour & Best Practices

Overview

Kount is a fraud prevention service that can be used to help identify and prevent potentially fraudulent transactions before they are submitted for processing. It works by collecting and analysing data from the customer’s checkout session, allowing the transaction to be reviewed and scored as part of the payment flow.

When using NMI, Kount can be built into a Gateway.js integration. Gateway.js is used to initialise and run Kount’s Data Collector on the checkout page, which returns a unique session ID for the transaction.

This article explains how to integrate Kount with Gateway.js, capture the Kount session ID, and pass that session ID through to NMI’s Payment API using the transaction_session_id field so the transaction can be linked to the collected Kount data.

Integrating Gateway.js & Kount 

In order to allow Kount to review and score transactions, integrators will need to utilize Gateway.js, by initializing the JavaScript Library and calling the Kount service within Gateway.js. This article will explain the flow and function that integrators should implement to their integrations in order to utilize the Kount service within Gateway.js: 

• The integration will first need to start by adding Gateway.js as the Gateway.js JavaScript library will be used to complete this integration.
• Once Gateway.js has been added, the integration will then need to initialize Gateway.js by utilizing the merchant's public Checkout Key. You can view your existing public keys or create a new one in the merchant portal's Security Key page.
  • Here is an example of how to initialize Gateway.js:

<script src="https://secure.nmi.com/js/v1/Gateway.js"></script>
<script>
//Initialize Gateway.js, use own Public Key
const gateway = Gateway.create('collect_checkout_0000000000000000000000000');
...

• Once Gateway.js has been initialized you will then be able to initialize the Kount service by calling gateway.getKount(). Kount must be initialized prior to the next step where we run Kount in order to collect data in order to determine the transactions score. 

//Initialize the Kount service
const kount = gateway.getKount();

• After Kount has been initialized you may now execute Kount to process transaction data via the Fraud protection service. Invoke the createSession() function to initiate Kount and capture its session ID using the .then method.

//Run Kount
kount.createSession().then((res) => {
    //Store session id
    const sessionId = res;

The above functions will call Kount, retrieve Kount's session id and store the session id within the set parameter sessionId.

• Once Kount has been run the integration will need to create a JavaScript object with additional transaction details. The details to include are credit card information (ccnumber, ccexp, cvv), currency, amount, email, city, address1, country, zip, first_name, last_name and the transaction_session_id. 
• The JavaScript object is necessary to collect transaction data for submission to the Payment API. This object contains all the required transaction details to successfully complete the transaction. Here is an example of how to set up the object with the necessary details.

const options = {
    ccnumber: '4111111111111111',
    ccexp: '1025',
    cvv: '999',
    currency: 'USD',
    amount: '10.00',
    email: 'none@example.com',
    phone: '8008675309',
    city: 'New York',
    state: 'NY',
    address1: '123 First St.',
    country: 'US',
    firstName: 'John',
    lastName: 'Doe',
    postalCode: '60001',
    transactionSessionId: sessionId
};

The above example shows the creation of a JavaScript object which holds transactional information for this transaction, including the transactionSessionId. Upon creation of the object the integration will now need to submit the transaction via a POST method to the Payment API to complete the transaction. 

Passing the Session ID to the Payment API

Once you have the object containing your transaction details and the Kount session ID, submit it to the Payment API the same way you would process any other transaction, the only Kount-specific requirement is that you include the session ID. (For full details on building and sending a Payment API transaction, see our Payment API documentation.)

• Pass the captured session ID to Payment API (transact.php) in the transaction_session_id field. This is what links the Data Collector information to the transaction so Kount can score it.
• Because the transaction is submitted with your private key, send it from your server, never expose the private key in client-side JavaScript.

Session ID Behaviour & Best Practices

• Generate a session on every form load. Run the Data Collector (call createSession()) immediately when the payment form loads so Kount has time to collect device data before the customer submits.
• Use the latest value. The Data Collector may be run multiple times; each call to createSession() returns a session ID. When you submit the transaction, use the most recent value.
• Session IDs are single-use. A session ID links one transaction to its Data Collector information. Generate a new, random/unpredictable ID per form load (sequential IDs are not permitted) and do not reuse an ID within a 30-day period.
• No session ID, no Kount. If you do not pass a transaction_session_id, Kount will not run and the transaction will not be scored.

Finally, listen for Gateway.js errors so any initialization or Kount failures are surfaced during integration and testing:

gateway.on('error', function (e) {
    console.error(e);
});

For full reference details on the Kount service within Gateway.js, see the NMI developer documentation at https://docs.nmi.com/docs/kount.