Using Kount with Gateway.js (REST API)

Table of Contents

1. Overview
2. Integrating Gateway.js & Kount
3. Passing the Session ID to the REST API
4. Session ID Behavior & 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 analyzing various data points before transaction submission. The seamless integration of Kount's Data Collector into checkout pages is facilitated through our REST API.

This article covers integrating Kount with Gateway.js when submitting transactions to the REST API (v5). If you are integrating against the Payment API (Classic API), please see the companion article Integrating Kount with Gateway.js (Payment 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. The client-side flow is identical regardless of which API you submit to, only the final submission step differs. This article will explain the flow and function that integrators should implement 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 (cardNumber, cardExpMonth, cardExpYear, cvv), currency, amount, email, city, address1, country, zip, firstName, lastName and the transactionSessionId. 
• The JavaScript object is necessary to collect transaction data for submission to the REST 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 = {
    cardNumber: '4111111111111111',
    cardExpMonth: '10',
    cardExpYear: '25',
    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 REST API to complete the transaction. 

Passing the Session ID to the REST API

Once you have the object containing your transaction details and the Kount session ID, submit it to the REST 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 REST API transaction, see our REST API documentation.)

• Pass the captured session ID to /api/v5/payments/sale as the top-level transaction_session_id property. 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 Behavior & 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.