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.
Data | Size | Description | Example |
---|---|---|---|
Ris.MerchantId |
6 | Six digit identifier issued by Kount. | 999666 |
Ris.Url |
na | HTTPS URL path to the company’s servers provided in boarding documentation from Kount. | https://risk.beta.kount.net |
Ris.API.Key |
Varies | API Key value copied from clipboard - originating from API Key page within Agent Web Console. | Alpha/Numeric hashed value provided by Kount |
Ris.Config.Key |
Varies | Config Key used in hashing method. | String key provided by Kount |
Ris.Connect.Timeout |
Varies | RIS connect timeout value measured in milliseconds. | 30000 |
LOG.LOGGER |
na | Specifies which logger to use: SIMPLE or NOP. | SIMPLE |
LOG.SIMPLE.LEVEL |
na | If SIMPLE logging is enabled, this lists logging levels in order of decreasing severity: FATAL, ERROR, WARN, INFO, DEBUG | WARN |
LOG.SIMPLE.FILE |
na | Name of the log file for SIMPLE logging. | Kount-Ris-DotNet-SDK.log |
LOG.SIMPLE.PATH |
na | SimpleLogger log path. This is the directory where the log file will be located. | C:\Logs |
LOG.SIMPLE.ELAPSED |
na | When is ON and SIMPLE logging is enabled, measure overall client request time in milliseconds and logging result. |
ON |
Making the First Call
- Add the
Kount.NET
Library to your Project. - Create a
Kount.Ris.Inquiry Object
, and then populate the setters. - Add cart data.
- Ask for the
responger(Inquiry.GetResponse())
. - 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.
- 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. - Setting the request mode. As mentioned previously, there are several request modes and
InquiryType.ModeQ
is the most used one. - 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.
- IP address of the customer. The merchant can discover it or it can be obtained through the Data Collector service.
- 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:
Inquiry MODE | SDK Constant | Description |
---|---|---|
Q |
InquiryType.ModeQ |
Default inquiry mode, internet order type |
P |
InquiryType.ModeP |
Used to analyze a phone-received order |
W |
InquiryType.ModeW |
Kount Central full inquiry with returned thresholds |
J |
InquiryType.ModeJ |
Kount Central fast inquiry with just thresholds |
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:
Update MODE | SDK Constant | Description |
---|---|---|
U |
UpdateType.ModeU |
Default update mode, only sends the update event |
X |
UpdateType.ModeX |
Sends the update event and RIS service returns a status response |
Mandatory Parameters
Parameter name | Setter | Mode Q |
Mode P |
Mode W |
Mode J |
Mode U |
Mode X |
---|---|---|---|---|---|---|---|
MODE |
SetMode |
Y | Y | Y | Y | Y | Y |
VERS |
SetVersion |
Y | Y | Y | Y | Y | Y |
MERC |
SetMerchantId |
Y | Y | Y | Y | Y | Y |
SITE |
SetWebsite |
Y | Y | Y | |||
SESS |
SetSessionId |
Y | Y | Y | Y | Y | |
CURR |
SetCurrency |
Y | Y | Y | Y | ||
TOTL |
SetTotl |
Y | Y | Y | Y | ||
CUSTOMER_ID |
SetKountCentralCustomerId |
Y | Y | ||||
PTYP |
Y | Y | Y | Y | |||
IPAD |
SetIpAddress |
Y | Y | Y | Y | ||
MACK |
SetMack |
Y | Y | Y | Y | Y | |
TRAN |
SetTransactionId |
Y | Y | ||||
PROD_TYPE |
* | Y | Y | Y | |||
PROD_ITEM |
* | Y | Y | Y | |||
PROD_QUANT |
* | Y | Y | Y | |||
PROD_PRICE |
* | Y | Y | Y | |||
ANID |
SetAnid |
Y |
Inquiry.setCart(collection<CartItem> cart)
method. If the shopping cart contains more than one entry, values for each parameter are transformed to single concatenated strings and then set to the corresponding parameter.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 theAUTH
field areA
for Authorized orD
for Decline. In orders whereAUTH = A
will aggregate towards order velocity of the persona while orders whereAUTH = D
will decrement the velocity of the persona.AVST
: Address Verification System Street verification response returned to merchant from processor. Acceptable values areM
for match,N
for no-match, orX
for unsupported or unavailable.AVSZ
: Address Verification System Zip Code verification response returned to merchant from processor. Acceptable values areM
for match,N
for no match, orX
for unsupported or unavailable.CVVR
: Card Verification Value response returned to merchant from processor. Acceptable values areM
for match,N
for no-match, orX
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.
- Create the class
Kount.Log.Factory.LoggerXFactory
that implementsKount.Log.Factory.LoggerFactory
. - Create
Kount.Log.Binding.LoggerX
class that implementsKount.Log.Binding.Logger
. This class is the interface to your custom loggerX. - 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);