Making requests to the Kount RIS

Configuration prerequisites and requirements

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 available through System.getProperty("kount.config.key");. You can set it:
  • on the command line like -Dkount.config.key=configKey or
  • through a configuration properties file that your application is going to read and load: kount.config.key=configKey

⚠️ If characters like ", \, or ' are present in the configuration key value, those need to be escaped on the command line.

Creating request objects

There are two types of requests that can be performed through the SDK -- Inquiry and Update. Those have various modes which will be discussed later on.

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

Let's create a sample Inquiry object and then send it to the RIS service.

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("[email protected]");
	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)

---

Next step: Get to know what Kount RIS is returning at the Response description section.
Next step: Check the Advanced wiki page for detailed information on request parameters and SDK usage.
Next step: Examine the SDK integration tests for more examples and insight on configuration