How to Integrate the RIS Java SDK

This document contains resources for the Kount RIS Java SDK. For a complete Kount integration you must include the Device Data Collector (DDC) as well as the RIS POST. It is recommended that you code for the DDC first.

The Kount RIS Java SDK provides means for:

• Building and sending requests to the RIS service
• Customer-side data verification
• Sensitive information protection

Installing the RIS Java SDK

The SDK contains several object model classes representing different request types as well as many enumeration-like objects, which can be used as request parameter values.

The KountRisClient class accomplishes client-server-client communication, secured TLS v1.2 and JWT API key.

The SDK utilizes specific hashing methods to encrypt and transmit sensitive client data like credit card numbers and various payment tokens.

SDK Requirements

In order to successfully integrate the Kount RIS Java SDK, the following requirements should be met:

• JRE/JDK 1.8+
• (optional) Apache Maven 3.x+
• (optional) Git 2.7.3+

The Kount RIS Java SDK requires JRE/JDK 1.8 in order to be used in an existing application.

The two optional requirements are given in case the SDK user prefers to download the SDK sources and build the SDK library from them. Please refer to the Frequently Asked Questions section for more information.

Downloading the Kount RIS Java SDK

There are two ways to obtain the Java SDK:

• Retrieving it as an Apache Maven dependency
• Building the binary .jar file from source

Maven dependency

Apache Maven is a software project management and comprehension tool. Based on the concept of a Project Object Model (POM), Maven can manage a project's build, reporting, and documentation from a central piece of information.

A dependency .jar can be obtained using the following dependency descriptor in your .pom:

<dependency>
  <groupId>com.kount</groupId>
  <artifactId>kount-ris-sdk</artifactId>
  <version>${kount.sdk.version}</version>
</dependency>

Where ${kount.sdk.version} is the library release which you are going to use.

Configuring the RIS Java SDK

Before you make your RIS call, you need to have received (or created) the following data from Kount:

• Merchant ID, 6-digit integer, referenced as MERCHANT_ID in code snippets
• Site ID, SITE_ID
• URL for (test) RIS calls
• API key, a JWT key used for authentication, apiKey
• An additional configuration key used within the SDK, configKey

Currently, all of the above parameters except apiKey and configKey have to be set through corresponding methods for each Request object that you create.

• apiKey is passed either as a Java File object or String object to the KountRisClient used to perform communication with the RIS server.
• configKey must be set as a system variable through one of two ways:
  • System variable through System.getProperty(“kount.config.key”);
  • Command line Dkount.config.key=configKey

Making Your First Call

Prior to following these steps you should have the Kount Java RIS SDK, a valid RIS URL, and a valid API Key.

1. Import Kount classes from SDK.
2. Create KountRisClient with the URL and API Key.
3. Create a new Inquiry() object.
4. Use client setters to add the transaction information.
5. Add cart information.
6. Call client.process(inquiry) and get a Response Object back.
7. Process the Response object.

package net.example;
 
import java.net.MalformedURLException;
import java.net.URL;
import java.util.ArrayList;
import java.util.Collection;
 
 
import com.kount.ris.Inquiry;
import com.kount.ris.KountRisClient;
import com.kount.ris.Response;
import com.kount.ris.util.CartItem;
import com.kount.ris.util.MerchantAcknowledgment;
import com.kount.ris.util.RisException;
import com.kount.ris.util.payment.Payment;
 
public class Example {
 
 
    public static void main(String[] args) throws MalformedURLException {
 
        URL url = new URL("https://risk.kount.net"");
        String apiKey = new String("23459856789");
        // Create a RIS client object with the target URL and your API key
        KountRisClient ris = new KountRisClient(url, apiKey);
 
 
        // Create and populate a new Request. The Request will be handed
        // off to the RIS client to make the call and provide the response.
        Inquiry req = new Inquiry();
        req.setMerchantId(555556);
        req.setSessionId("faa6370074b53928bc51ef913441e0cd");
        Payment payment = new Payment("CARD", "4111111111111111");
        req.setCurrency("USD");
        req.setPayment(payment);
        req.setTotal(125);
        req.setCustomerName("John Doe");
        req.setEmail("johndoe@test.com");
        req.setIpAddress("127.0.0.1");
        req.setMerchantAcknowledgment(MerchantAcknowledgment.YES);
        req.setWebsite("DEFAULT");
        CartItem item0 = new CartItem("SURROUND SOUND", "HTP-2920", "Pioneer High Power 5.1 Surround Sound System", 1, 49999);
        CartItem item1 = new CartItem("BLURAY PLAYER", "BDP-S500", "Sony 1080p Blu-Ray Disc Player", 1, 69999);
        Collection<CartItem> cart = new ArrayList<>();
        cart.add(item0);
        cart.add(item1);
        req.setCart(cart);
        try {
            // This is the first point at which the code actually calls the Kount
            // services. Everything prior to this is simply setting up the payload.
            Response response = ris.process(req);
            String responseText = "Transaction ID: " + response.getTransactionId() + "\n\n";
            responseText += response;
            System.out.print(responseText);
        } catch (RisException risException) {
            System.out.print(risException.getMessage());
        }
    }
}

Creating Request Objects

There are two types of requests that can be performed through the SDK: Inquiry and Update. Both have various modes. Refer to Request Types and Parameters for more information.

The usual structure of a Request usually consists of three parts:

• Information about the merchant and processing instructions for the RIS service
• Information about the customer making a purchase: personal data, geo-location, etc.
• Information about the purchase: product name, category, quantity, price

public void evaluateInquiry() throws Exception {
	Inquiry i = new Inquiry();

	setMerchantInformation(i);
	setCustomerInformation(i);
	setPurchaseInformation(i);

	KountRisClient client = new KountRisClient(
		new URL("https://kount.ris/url"), new File("/path/to/api.key")); // 1

	Response response = client.process(i);

	// do stuff with response
}

public void setMerchantInformation(Inquiry i) {
	i.setMerchantId(MERCHANT_ID);
	i.setWebsite(SITE_ID);
	i.setMode(InquiryMode.INITIAL_INQUIRY); // 2

	i.setMerchantAcknowledgment(MerchantAcknowledgment.YES);
}

private void setCustomerInformation(Inquiry i) {
	i.setSessionId("session-id-max-32-chars"); // 3
	i.setIpAddress("192.168.32.16"); // 4
	i.setPayment(new CardPayment("credit-card-number")); // 5

	i.setCustomerName("Customer Name");
	i.setEmail("customer.name14@email.com");
	i.setShippingAddress(new Address());
}

private void setPurchaseInformation(Inquiry i) {
	i.setCurrency("USD");
	i.setTotal(1000); // 6
	CartItem cartItem = new CartItem(
		"sports", "sport product name", 
		"sport product description", 2, 500);

	i.setCart(Collections.singletonList(cartItem));
}

Explanation of the request

Here is a short description of what's going on during request creation, following the numbered comments in code

1. Creating the communication client, requires the RIS service URL and a path to the provided API key file. The API key is set as request header for the network request.
2. Setting the request mode. As mentioned previously, there are several request modes and InquiryMode.INITIAL_INQUIRY is the most used one. Please check the Advanced page for more information on request modes.
3. Setting a session identifier. This ID should be unique for a 30-day span and is used to track all changes regarding the purchase described in the request. More information on the Advanced page.
4. IP address of the customer. The merchant can discover it or it can be obtained through the Data Collector service.
5. Set this to a correct credit number or select another payment method (for test purposes).
6. The total purchase amount represented in the lowest possible currency denomination (example: cents for US Dollars)

RIS Response

After a merchant has posted RIS information to Kount, a key-value pair string will be returned back to the merchant. The RIS response format will be the same that was specified in the RIS request, with the default being named pairs. Each data field must be invoked by getter methods on the Response object from the SDK. The merchant can then use the RIS response to automate the order management process by keying off of the AUTO field and can utilize any of the additional data returned for internal processing.

An important use of the RIS response is the ability to view any warnings or errors that were made during the RIS post from the merchant. All warnings will be displayed in the response and if errors do occur the RIS response will be returned with a MODE = E. More information on warnings and errors can be found at the Troubleshooting section.

If Kount Data Collector was used to collect customer information, the KAPT field can be checked to determine if this process was successful. KAPT = Y means successful, KAPT = N means the process was unsuccessful.

RIS Payment Encryption Options

The Kount RIS Java SDK defines a group of objects representing various payment types. Using those payment types with the Request.setPayment(...) method automatically sets the required PTYP parameter and other parameters corresponding to the selected payment type.

Supported payment types:

• ApplePayPayment
• BPayPayment
• CardPayment
• CarteBleuePayment
• CheckPayment
• ElvPayment
• GiftCardPayment
• GiroPayPayemnt
• GooglePayment
• GreenDotMoneyPakPayment
• InteracPayment
• MercadoPagoPayment
• NetellerPayment
• PaypalPayment
• PoliPayment
• SingleEuroPaymentsArea
• SkrillMoneybookersPayment
• SofortPayment
• TokenPayment

There are also several "system" payment types:

• NoPayment
• BillMeLaterPayment

For the latest list of supported payment types as well as their corresponding PTYP parameter values, please, refer to the RIS RESTful API Payments.

If the SDK does not contain your preferred payment type, use the generic methods:

// option 1
Payment unlistedPayment = new Payment("XYZ", "XYZ-payment-token");
request.setPayment(unlistedPayment);

// option 2
request.setPayment("XYZ", "XYZ-payment-token");

Request Types and Parameters

The two major request types, Inquiry and Update, are configured by setting the MODE parameter to the correct value.
Use Inquiry for initial registration of the purchase in the Kount system. It has four available values for the MODE parameter:

Use Update whenever there are changes to a given order that need to be updated in the Kount system. Update has two available values for the MODE parameter:

Mandatory Parameters

Optional Parameters

Kount's RIS provides many optional request parameters to increase precision when making a decision about a given purchase/order.

• AUTH: Authorization Status returned to merchant from processor. Acceptable values for the AUTH field are A for Authorized or D for Decline. In orders where AUTH = A will aggregate towards order velocity of the persona while orders where AUTH = D will decrement the velocity of the persona.
• AVST: Address Verification System Street verification response returned to merchant from processor. Acceptable values are M for match, N for no-match, or X for unsupported or unavailable.
• AVSZ: Address Verification System Zip Code verification response returned to merchant from processor. Acceptable values are M for match, N for no match, or X for unsupported or unavailable.
• CVVR: Card Verification Value response returned to merchant from processor. Acceptable values are M for match, N for no-match, or X unsupported or unavailable.
• LAST4: Last 4 numbers of Credit Card Value.
• LBIN: Captures 6-8 characters of BIN data

User Defined Fields (UDFs)

You can create User Defined Fields (UDFs) to include additional information related to your business that is not a standard field in the Transactions Details page in the AWC. Once you have defined the UDF in the AWC, you can pass this data into Kount via an array called UDF as key-value pairs where the label is the key and the data passed in is the value. For more information on creating UDF, review How to Manage User Defined Fields (UDF).

Predictive Response

Predictive Response is a mechanism that can be used by Kount merchants to submit test requests and receive back predictable RIS responses. This means that a merchant, in order to test RIS, can generate a particular request that is designed to provide one or more specific RIS responses and/or errors. The predictive response inquiries are not actual RIS inquiries, which means the data will never be submitted to the Kount internal database.

An example would be if a merchant wanted to submit a RIS request that would return the very specific responses SCOR = 71, AUTO = E, and GEOX = CA.

Predictive Responses are created using the UDF (User Defined Fields) override option. These User Defined Fields do not need to be created through the Agent Web Console, they can be simply passed in as additional fields in the Predictive Response RIS inquiry.

All other elements of the RIS request you submit must be valid elements and contain the minimum set of required RIS keys.

The basic syntax is: UDF[~K!_label]="foo" ~K!_ is the prefix, label is the desired field for which you want a response, such as SCOR or ERRO, and after the equal sign (=), enter the specific value you want returned. The ~K!_ prefix is required to trigger the UDF to become a predictive response field.

Example 1

You want to send in a request that will result in a Kount Score of 18, an Auto Decision of E, and a 601 System Error code.

Request

    UDF[~K!_SCOR]=18
    UDF[~K!_AUTO]=E
    UDF[~K!_ERRO]=601

Response

    SCOR=18
    AUTO=E
    ERRO=601

Example 2

You want to pass in a request that will result in a Kount Score of 42, an Auto Decision of Decline and a GEOX of Nigeria.

Request

    UDF[~K!_SCOR]=42
    UDF[~K!_AUTO]=D
    UDF[~K!_GEOX]=NG

Response

    SCOR=42
    AUTO=D
    GEOX=NG

You can use UDF overrides to pass in an unlimited number of mock requests but all of the fields you pass in that are not overrides must be valid. In the response, all of the other elements, besides the UDF overrides will be the default values, including MODE and MERC.

Session related parameters

There are a few parameters responsible for maintaining connection between linked interactions with the RIS. They are transported as a part of the Request/Response objects during standard RIS communication.

SESS parameter

This parameter should be created by the merchant at the start of each new customer purchase. SESS is used to join the customer device data with the order data sent with the RIS request. If the merchant uses the Device Data Collector service to obtain customer device information, then the same SESS value must be used for all RIS calls starting with the one to the Device Data Collector service. Requirements for the parameter value are:

• Alphanumeric
• 1-32 characters
• Value should be unique over a thirty-day period of time SESS is a mandatory parameter set by Request.session_set(string) method.

TRAN parameter

The TRAN parameter is required for Update calls to Kount RIS. Its value is created by Kount and is returned within the Response object for the first RIS Inquiry. For all subsequent events, modifying this particular customer order, the TRAN parameter should be set to the Kount-created value.

Frequently Asked Questions