How to Integrate the RIS Ruby SDK

The official Kount Complete RIS wrapper. It provides simple methods to execute RIS calls. The kount_complete gem for Ruby provides a configurable wrapper to the transport layer for RIS.

All interaction with the wrapper is done using native Ruby Hashes and Arrays instead of enforcing rigid getters and setters for every RIS element. This allows a customer to integrate the gem using the current version and then easily access new functionality with the original gem as new RIS versions are released.

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 Ruby SDK

Installation

gem install kount_complete

require 'kount'
client = Kount.new(options)

Configuring the RIS Ruby SDK

You can manage your config parameters (yaml, scripted, etc.) however you want as long as you provide the Kount class a hash with: :merchant_idA, :ksalt, and :key. This minimal config defaults to production settings.

options = {
	merchant_id: MERCHANT_ID,  #required (6 digit number, assigned by Kount)
	key:         KEY,          #required (created in the AWC web app by merchant)
	ksalt:       KSALT        #required (provided by Kount)
}
client = Kount.new(options)

There are additional parameters that are optional depending on your setup and environment (test, beta, other).

• :is_test (defaults to false)
• :endpoint (defaults to production value)
• :version (defaults "0700")

When :is_test is omitted or set to false, the RIS endpoint will default to production values. When :is_test is set to true, the RIS endpoint will default to Kount test server settings; however, both endpoints can be overridden if needed.

The key required for RIS is defined by the merchant in the Kount AWC.

The :version is to specify which version of the RIS interface is being called. Newer interface versions might require additional parameters in the client.get_response call and provide additional/different return parameters.

Making Your First Call

Perform the following steps.

1. Import the httr library.
2. Create the message body.
3. Create the http header.
4. Post the data.
5. Process the results.

Example RIS Calls

library(httr)
   
  kountAPIkey <- "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1NTU1NTIiLCJhdWQiOiJLb3VudC4xIiwiaWF0IjoxNDMxMzgyMjExLCJzY3AiOnsia2EiOm51bGwsImtjIjpudWxsLCJhcGkiOnRydWUsInJpcyI6dHJ1ZX19.at8NUkI9oGQKZsEKzi3jrSU5P67p-AxM_TGXr5ZgEec"
   
  kountBody = paste0(
  'VERS=0630&',
  'MODE=Q&',
  'MERC=555552&',
  'SESS=QWER2314567&',
  'FRMT=XML&',
  'CURR=USD&',
  'TOTL=499&',
  'EMAL=approve@flexshopper.com&',
  'PTYP=NONE&',
  'PTOK=&',
  'IPAD=127.0.0.1&',
  'MACK=Y&',
  'SITE=DEFAULT&'
  'PROD_TYPE[0]=Test&',
  'PROD_DESC[0]=Test&',
  'PROD_QUANT[0]=1&',
  'PROD_PRICE[0]=999&',
  'PROD_ITEM[0]=Test&',
  'PROD_TYPE[1]=Test1&',
  'PROD_DESC[1]=Test1&',
  'PROD_QUANT[1]=1&',
  'PROD_PRICE[1]=991&',
  'PROD_ITEM[1]=Test1&',
  'SITE=DEFAULT'
  );
 
  httpheader <- c(Accept="text/plain; charset=UTF-8",
                  "Content-Type"="application/x-www-form-urlencoded")
   
  a <-  httr::POST(url="https://risk.test.kount.net"",
             body=kountBody,
             add_headers(httpheader,
                         paste0("X-Kount-Api-Key", kountAPIkey)))
 
 
print(a)

Inquiry (Mode Q)

client = Kount.new(options)

A hash can be provided during object creation:

inquiry = Kount::Inquiry.new(
    SITE: "DEFAULT",
    MACK: "Y",
    AUTH: "A",
    ORDR: "3458",
    TOTL: "5000",
    EMAL: "joe@example.com"
    )

Additional parameters can be added using a hash:

inquiry.add_params(CURR: "USD", IPAD: "127.0.0.1", SESS: "456789y0nn87tn")

The add_payment method is provided to encapsulate the KHASH logic for credit cards, gift cards, and other payment types. It handles the setting of: :PTYP, :PTOK, and :PENC when needed. Kount::PaymentTypes is a set of constants defined with supported payment types.

inquiry.add_payment(Kount::PaymentTypes::CREDIT_CARD, "4359873465893466783")

Every Inquiry (mode Q) requires cart data. Use the add_item and add_cart to simplify the conversion to form data. It handles the setting of: :PROD_TYPE, :PROD_DESC, :PROD_ITEM, :PROD_PRICE, and :PROD_QUANT.

cart = Kount::Cart.new()

The params are: cart.add_item(Type, Description, Item, Quantity, Price).

cart.add_item('64 inch LCD TV', 'Electronics', 'Television', '1', '45')
cart.add_item('32 inch LCD TV', 'Electronics', 'Television', '44', '4564')
cart.add_item('48 inch Plasma TV', 'Electronics', 'Television', '8', '765476')
inquiry.add_cart(cart)

Just like with cart items, the form element formatting for UDFs can be tricky, so a quick convenience method is available on the Request class for adding them.

inquiry.add_udf('UDF_LABEL', 'UDF value')

The get_response is the first point at which the Kount server is contacted. Everything it needs to provide the response should be included in the inquiry payload. Response format is a native Ruby Hash.

#response = client.get_response(inquiry)
response = Response::Resp.new(client.get_response(inquiry))

Update (Mode U and X)

The Kount::Update.new() automatically sets the following parameters based on your configuration settings: :MERC, :MODE, :VERS, and :FRMT. The default is MODE: 'U' for Kount::Update so MODE: 'X' will need to be added manually if you need mode X.

update = Kount::Update.new({
    TRAN: "30SP03DL69JS", # TRAN is one of the return values from a MODE Q call
    SESS: "456789y0n34b07y34n807yn87tn",
    MACK: "Y",
    AUTH: "D",
    ORDR: "3458",
    })
#response = client.get_response(update)
response = Response::Resp.new(client.get_response(update))

Inquiry (Mode J and W)

The Kount::Inquiry.new() automatically sets the following parameters based on your configuration settings: :MERC, :VERS, and :FRMT. However, you need to provide your desired :MODE setting since it will otherwise default to Q. The :CUSTOMER_ID parameter is also required for both MODE J and W.

inquiry = Kount::Inquiry.new({
    MODE: "J",
    CUSTOMER_ID: "Customer 1",
    })
#response = client.get_response(inquiry)
response = Response::Resp.new(client.get_response(inquiry))

Inquiry (Mode P)

Just like MODE J and W, you need to provide your desired :MODE setting since it will otherwise default to Q. Also required for MODE P is the :ANID parameter instead of the :CUSTOMER_ID parameter.

inquiry = Kount::Inquiry.new({
    MODE: "P",
    ANID: "9991230000", # Phone number
    })
#response = client.get_response(inquiry)
response = Response::Resp.new(client.get_response(inquiry))

RIS Payment Encryption Options

KHASH

Convert credit card number to KHASH without RIS_KEY or Endpoint configuration.

The only required option setting for credit card KHASH is the KSALT. The secret KSALT value is provided to clients only.

Kount::SecurityMash.hash_credit_card(plain_text, ksalt)

For the GIFT payment type, a merchant ID is also required.

Kount::SecurityMash.hash_gift_card(plain_text, ksalt, merchant_id)

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

Frequently Asked Questions