How to Integrate the RIS .NET SDK

For a complete Kount integration you need to include the Device Data Collector as well as the RIS post. It is recommended that you code for the Device Data Collector first.

Installing the RIS .NET SDK

To install the latest RIS .NET SDK, Kount recommends using the NuGet package manager. Enter the following command in the NuGet console:

PM> Install-Package Kount.Net.RisSDK

For information on how to build the RIS .NET SDK from the GitHub SDK repository, refer to the FAQ section at the end of this document.

Configuring the RIS .NET SDK

Before you make your first RIS call, you must have the following:

• Merchant ID, 6-digit integer, referenced as Ris.MerchantId in code snippets (provided by your Kount representative)
• URL for (test) RIS calls as Ris.Url
• API key, an alphanumeric key used for authentication, Ris.API.Key (retrieved from the Kount Command AWC)
• An additional configuration key used within the SDK, Ris.Config.Key

In your App or Web config file, in the appSettings section, add your basic configuration. Before using the SDK, you must set the Merchant ID and RIS URL to the config file. The following displays an example config file (a template of App.config is also included in KountRisSDK project):

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<appSettings>

<add key="Ris.MerchantId" value="999666" />

<add key="Ris.Url" value="https://risk.test.kount.net" />

<add key="Ris.API.Key" value="zI1NiJ9.eyJpc3MiOiI5Owqrtjul;kshdWQiOiJLb3VudC4xIiwiaWF0IjoxNDg4NTYzMzgzLCJz" />
<!--
Config Key used in hashing method
-->
<add key="Ris.Config.Key" value="Confing Key set here" />
<!--
RIS connect timeout value measured in milliseconds. Recommended value
is 30000 (30 seconds).
-->
<add key="Ris.Connect.Timeout" value="10000" />

<add key="LOG.LOGGER" value="SIMPLE" />
<!--
Logging level for SimpleLogger if it is enabled.
Acceptable logging levels in order of decreasing severity are FATAL,
ERROR, WARN, INFO, and DEBUG.
-->
<add key="LOG.SIMPLE.LEVEL" value="DEBUG" />
<!--
Specify the file name where the SimpleLogger will log messages to.
-->
<add key="LOG.SIMPLE.FILE" value="Kount-Ris-DotNet-SDK.log" />
<!--
SimpleLogger log path. This is the directory where the log file will be
located. This directory must already exist.
-->
<add key="LOG.SIMPLE.PATH" value="C:\Logs" />
<!--
Optional setting. When is `ON` and SIMPLE logging is enabled, measure overall client
request elapsed time in milliseconds and logging result. Default value is `OFF`.
-->
<add key="LOG.SIMPLE.ELAPSED" value="ON" />
</appSettings>
</configuration>

The table below describes the required static settings found in the SDK.

Making the First Call

1. Add the Kount.NET Library to your Project.
2. Create a Kount.Ris.Inquiry Object, and then populate the setters.
3. Add cart data.
4. Ask for the responger(Inquiry.GetResponse()).
5. Process the Kount.Ris.Response object returned.
   

       Kount.Ris.Inquiry inq = new Kount.Ris.Inquiry();
       
       // Create masked inquiry with CARD payment
       inq.SetPayment(Kount.Enums.PaymentTypes.Card, "5789372819873789");
       // Merchants acknowledgement to ship/process the order
       inq.SetMack('Y');
       // client email
       inq.SetEmail("joe@domain.com");
       // Set default inquiry mode, internet order type
       inq.SetMode(InquiryType.ModeQ);
       inq.SetSessionId(sessionId);
       // IP address of the customer
       inq.SetIpAddress("165.53.125.33");
       inq.SetWebsite("DEFAULT");
       // total purchase amount
       inq.SetTotal(5000);
       ArrayList cart = new ArrayList();
       cart.Add(new Kount.Ris.CartItem("Electronics", "TV","Big TV", 1, 24900));
       inq.SetCart (cart);
       Kount.Ris.Response response = inq.GetResponse();
       Console.WriteLine("RESPONSE: " + response.ToString());
       

Request Explanation

This is a description of what happens during request creation.

1. Create masked inquiry with CARD payment, and populate the setters.
   
   Note: KHASH is the default implementation for payment encryption and requires a config key. Masking overrides the default KHASH implementation, masks payment tokens, and does not require a config key.
2. Setting the request mode. As mentioned previously, there are several request modes and InquiryType.ModeQ is the most used one.
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. 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 is returned to the merchant. The RIS response format is 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 are displayed in the response and if errors do occur the RIS response will be returned with a MODE = E.

If the Kount Device 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

When using the SDK, KHASH and MASK are available.

KHASH

In .Net RIS SDK version 5.0.0+, all payment tokens are hashed (one-way encryption) prior to being transmitted to Kount. No credit card numbers, Paypal payment IDs, check numbers, Google Checkout IDs, Bill Me Later IDs, Green Dot MoneyPak IDs, gift card numbers, etc are transmitted in plain text. When the payment type is a credit card (optional for all other payment types), you must send data in the LAST4 input field. The value of this field is the last four numbers/characters of the payment token. The SDK automatically sets this value prior to hashing the payment token for all payment types.

Output : BIN + 14 alpha-numeric characters.
Example: "123456A12C34E56G7DFG"

KHASH Code Example

/// <summary>
/// Create inquiry with CARD payment
/// </summary>
/// <param name="cardNumber">card number</param>
/// <param name="sid">session id</param>
/// <param name="orderNum">order number</param>
/// <returns>inquiry</returns>
public static Inquiry CreateInquiry(string cardNumber, out string sid, out string orderNum)
{
// create inquiry with default settings
Inquiry inquiry = DefaultInquiry(out sid, out orderNum);
// hashing card number
inquiry.SetCardPayment(cardNumber);

return inquiry;
}

MASK

In SDK version 6.9.5 is implemented new method Request.SetCardPaymentMasked(string cardNumber), which sets a card payment and masks the card number.

MASK Code Example

/// <summary>
/// Create masked inquiry with CARD payment
/// </summary>
/// <param name="cardNumber">card number</param>
/// <param name="sid">session id</param>
/// <param name="orderNum">order number</param>
/// <returns>masked inquiry</returns>
public static Inquiry CreateInquiryMasked(string cardNumber, out string sid, out string orderNum)
{
// create inquiry with default settings
Inquiry inquiry = DefaultInquiry(out sid, out orderNum);
// mask card number
inquiry.SetCardPaymentMasked(cardNumber);

return inquiry;
}

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).

Session Related Parameters

There are parameters responsible for maintaining the 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 is created by the customer (merchant) at the start of each new end-user purchase. SESS is used to join the customer device data with the order data sent with the RIS request. If the merchant uses the Kount Device Data Collector service to obtain customer device information, then the same SESS value must be used for all RIS calls - starting with the call to the Device Data Collector service.

Requirements for the SESS parameter value:

• Alphanumeric
• 1-32 characters
• Value must be unique over a thirty-day period of time SESS is a mandatory parameter set by Request.SetSessionId(string sessionId); 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 customer order, the TRAN parameter should be set to the Kount-created value.

Configuring the Logger

The Kount RIS .NET SDK includes a basic logging framework abstraction. This allows your logging framework to be integrated with the SDK. By default, the SDK provides two basic loggers: NOP and SIMPLE.

NOP is a logger that silently discards all logging. This is the default logger used by the .NET RIS SDK. SIMPLE is a logger that logs messages to a specified file on the SDK host-machine.
SIMPLE logger can be configured in your App.config. The following logging levels are available in order of decreasing severity: FATAL, ERROR, WARN, INFO, and DEBUG.

Kount recommends the following steps to integrate a custom logger with the SDK.

1. Create the class Kount.Log.Factory.LoggerXFactory that implements Kount.Log.Factory.LoggerFactory.
2. Create Kount.Log.Binding.LoggerX class that implements Kount.Log.Binding.Logger. This class is the interface to your custom loggerX.
3. Set your logger factory using the method Kount.Log.Factory.LogFactory.SetLoggerFactory().

Logging Code Example

/// <summary>
/// A class demonstrating how to use logging
/// </summary>
public class ExampleClient
{
/// <summary>
/// The main entry point for the application.<br/>
/// <b>Author:</b> Kount <a>custserv@kount.com</a>;<br/>
/// <b>Version:</b> 6.5.0. <br/>
/// <b>Copyright:</b> 2010 Keynetics Inc <br/>
/// </summary>
[STAThread]
public static void Main()
{
ILoggerFactory factory = LogFactory.GetLoggerFactory();
ILogger logger = factory.GetLogger("Example Client");
logger.Debug("Hello World");
logger.Info("Hello World");
logger.Warn("Hello World");
logger.Error("Hello World");
logger.Fatal("Hello World");

// How to log messages and exceptions.
try
{
Exception e = new Exception("Logging an exception");
throw e;
}
catch (Exception e)
{
logger.Debug("Hello World", e);
logger.Info("Hello World", e);
logger.Warn("Hello World", e);
logger.Error("Hello World", e);
logger.Fatal("Hello World", e);
}
}
}

Abstract Logger

The end-user can provide their implementation of ILogger and use it to capture Kount SDK logs. The abstract logger overrides the SimpleLogger configuration.

Create the ILogger instance and pass it to the Kount Inquiry object constructor.

Example

using var loggerFactory = LoggerFactory.Create(builder =>
{
builder.
SetMinimumLevel(LogLevel.Error)
.AddConsole().AddFile("C:/Logs/logfilename.txt");
});
ILogger logger = loggerFactory.CreateLogger<Program>();
// Passing ILogger reference to Kount.Ris.Inquiry
Inquiry inquryObj = new Inquiry(logger);

Frequently Asked Questions