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

Gateway.js, a JavaScript library, empowers merchants to tailor their integrations and incorporate additional gateway services like Kount. Kount serves to identify and prevent fraudulent transactions by analysing various data points before transaction submission. The seamless integration of Kount's Data Collector into checkout pages is facilitated through our Payment API.

This article covers integrating Kount with Gateway.js when submitting transactions to the Payment API (Classic API). If you are integrating against the REST API (v5), please see the companion article Integrating Kount with Gateway.js (REST API).

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.