How to Integrate the RIS Python SDK

This document contains resources for the Kount Python SDK. The Kount RIS Python SDK provides information about:

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

Installing the RIS Python SDK

Kount recommends using the pip package manager pip install kount_ris_sdk to install the latest RIS Python SDK. Kount allows developers to download the SDK library from the Python SDK GitHub repository; however, Kount recommends using pip.

Follow the steps below to download from the SDK library:

1. Clone the SDK repository to your machine.
2. Use your preferred Git client
3. Console:
   git clone https://github.com/Kount/kount-ris-python-sdk.git
   git clone git@github.com:Kount/kount-ris-python-sdk.git
4. Use your preferred python IDE.

Configuring the RIS Python 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: url
• URL for (test) RIS calls: url_api, currently url_api = "https://risk.beta.kount.net" in test_api_kount.py
• Hashing configurationKey phrase used to encrypt sensitive data, configurationKey – must be configured in kount.settings:
  • as environment variable | K_KEY
  • any convenient file /like local_settings.py for Django users/
• API key, a JWT key used for authentication, key parameter in class Client client.py, used to perform communication with the RIS server.

Making Your First Call

There are two types of requests that can be performed through the SDK: Inquiry and Update. 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

Example of an Inquiry object being sent to the RIS service /see test_inquiry.py/.

#python
from kount.util.khash import Khash
from kount.settings import configurationKey as iv

Khash.set_iv(iv)

MERCHANT_ID = 999667
EMAIL_CLIENT = "customer.name@email.com"
SHIPPING_ADDRESS = Address("567 West S2A1 Court North", "",
                           "Gnome", "AK", "99762", "US")
PTOK = "0007380568572514"
SITE_ID = "192.168.32.16"
URL_API = "https://kount.ris/url"
API_KEY = "real api key"

def evaluate_inquiry():
    session_id = generate_unique_id()[:32]
    inquiry = Inquiry()

    # set merchant information, see default_inquiry() in test_basic_connectivity.py
    inquiry.merchant_set(MERCHANT_ID)
    inquiry.request_mode(INQUIRYMODE.DEFAULT)
    inquiry.merchant_acknowledgment_set(MERCHANTACKNOWLEDGMENT.TRUE)
    inquiry.website("DEFAULT")

    #~ set customer information
    inquiry.unique_customer_id(session_id[:20])
    inquiry.ip_address(SITE_ID)
    payment = CardPayment(PTOK, khashed=False)   # credit-card-number
    #~ or for khashed token
    #~ payment = CardPayment(PTOK)   # credit-card-number, khashed=True *default value*
    inquiry.payment_set(payment)
    inquiry.customer_name("SdkTestFirstName SdkTestLastName")
    inquiry.email_client(EMAIL_CLIENT)
    inquiry.shipping_address(SHIPPING_ADDRESS)

    # set purchase information
    inquiry.currency_set(CURRENCYTYPE.USD)
    inquiry.total_set('123456')
    cart_item = []
    cart_item.append(CartItem("SPORTING_GOODS", "SG999999",
                              "3000 CANDLEPOWER PLASMA FLASHLIGHT",
                              '2', '68990'))
    inquiry.shopping_cart(cart_item)

    client = Client(URL_API, API_KEY)
    response = client.process(params=self.inq.params)
    response_params = Response(response).params

    # do stuff with response

Request Explanation

Here is a short description of the request creation process.

1. Creating the communication client, requires the RIS service URL and provided API key. 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. 
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.
4. IP address of the customer. The merchant can discover it or it can be obtained through the Device 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)
7. Different payment types /user defined/ can be created with NewPayment or Payment:
   

   NewPayment(payment_type="PM42", payment_token=token) # default khashed=True
       Payment("PM42", token, False)
       Payment("PM42", token) # default khashed=True

RIS Response

After a merchant has posted RIS information to Kount, a key-value pair string is returned back 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 will be displayed in the response and if errors do occur the RIS response will be returned with a MODE = E /if inquiry.params["FRMT"] is not set/ or {"MODE": "E", "ERRO": "201"} /if inquiry.params["FRMT"] = "JSON"/.  A Response.get_errors() returns an error list.

RIS Payment Encryption Options

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

Supported payment types:

• CardPayment
• CheckPayment
• GiftCardPayment
• GooglePayment
• GreenDotMoneyPakPayment
• PaypalPayment
• Apple Pay
• BPAY
• Carte Bleue
• ELV
• GiroPay
• Interac
• Mercado Pago
• Neteller
• POLi
• Single Euro Payments Area
• Skrill/Moneybookers
• Sofort
• Token

There are also several "system" payment types:

• NoPayment
• BillMeLaterPayment

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

#~ uncomment this if you'd like to get the configurationKey from the environment
#~ import os
#~ try:
    #~ configurationKey = os.environ['K_KEY']
#~ except KeyError:
    #~ print("The default fake configurationKey set. Required actual one from Kount")
    

~/Kount$ python3 -m pytest tests
=============== test session starts =============================
platform linux -- Python 3.6.1, pytest-3.1.0, py-1.4.33, pluggy-0.4.0
metadata: {'Platform': 'Linux-4.10.0-21-generic-x86_64-with-Ubuntu-17.04-zesty', 'Plugins': {'html': '1.14.2', 'metadata': '1.5.0'}, 'Packages': {'py': '1.4.33', 'pytest': '3.1.0', 'pluggy': '0.4.0'}, 'Python': '3.6.1'}
rootdir: /home/dani/Kount, inifile:
plugins: metadata-1.5.0, html-1.14.2
collected 91 items

tests/test_address.py ...
tests/test_api_kount.py .......
tests/test_base85_encode_decode.py ....
tests/test_basic_connectivity.py ..........
tests/test_bed_examples.py ..
tests/test_inquiry.py ...
tests/test_khash.py ...........
tests/test_payment.py .....
tests/test_ris_test_suite.py ..........................
tests/test_ris_validation_exception.py ........
tests/test_ris_validator.py ...
tests/test_validation_error.py ........
tests/test_xmlparser.py .


===========================================================91 passed in 71.87 seconds ==========
    

~/Kount$ python -m pytest tests
=========================================================================================== test session starts ============================================================================================
platform linux2 -- Python 2.7.13, pytest-3.1.1, py-1.4.33, pluggy-0.4.0
metadata: {'Python': '2.7.13', 'Platform': 'Linux-4.10.0-22-generic-x86_64-with-Ubuntu-17.04-zesty', 'Packages': {'py': '1.4.33', 'pytest': '3.1.1', 'pluggy': '0.4.0'}, 'Plugins': {'html': '1.14.2', 'metadata': '1.5.0'}}
rootdir: /home/dani/Kount, inifile:
plugins: metadata-1.5.0, html-1.14.2
collected 27 items / 4 errors

================================================================================================== ERRORS ==================================================================================================
_________________________________________________________________________________ ERROR collecting tests/test_api_kount.py _________________________________________________________________________________
tests/test_api_kount.py:14: in <module>
    import inittest
tests/inittest.py:20: in <module>
    Khash.set_iv(iv)
kount/util/khash.py:73: in set_iv
    cls.verify()
kount/util/khash.py:63: in verify
    raise ValueError(mesg)
E   ValueError: Configured configurationKey  is incorrect.
--------------------------------------------------------------------------------------------- Captured stderr ----------------------------------------------------------------------------------------------
No handlers could be found for logger "kount.khash"
____________________________________________________________________________ ERROR collecting tests/test_basic_connectivity.py _____________________________________________________________________________
tests/test_basic_connectivity.py:16: in <module>
    import inittest
tests/inittest.py:20: in <module>
    Khash.set_iv(iv)
kount/util/khash.py:73: in set_iv
    cls.verify()
kount/util/khash.py:63: in verify
    raise ValueError(mesg)
E   ValueError: Configured configurationKey is incorrect.
___________________________________________________________________________________ ERROR collecting tests/test_khash.py ___________________________________________________________________________________
tests/test_khash.py:9: in <module>
    import inittest
tests/inittest.py:20: in <module>
    Khash.set_iv(iv)
kount/util/khash.py:73: in set_iv
    cls.verify()
kount/util/khash.py:63: in verify
    raise ValueError(mesg)
E   ValueError: Configured configurationKey  is incorrect.
______________________________________________________________________________ ERROR collecting tests/test_ris_test_suite.py _______________________________________________________________________________
tests/test_ris_test_suite.py:9: in <module>
    from test_basic_connectivity import generate_unique_id, default_inquiry
/usr/local/lib/python2.7/dist-packages/_pytest/assertion/rewrite.py:216: in load_module
    py.builtin.exec_(co, mod.__dict__)
tests/test_basic_connectivity.py:16: in <module>
    import inittest
tests/inittest.py:20: in <module>
    Khash.set_iv(iv)
kount/util/khash.py:73: in set_iv
    cls.verify()
kount/util/khash.py:63: in verify
    raise ValueError(mesg)
E   ValueError: Configured configurationKey is incorrect.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Interrupted: 4 errors during collection !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
=================================================== 4 error in 0.29 seconds =================================

~/Kount$ coverage run -m unittest discover tests
.....................................................................................
----------------------------------------------------------------------
Ran 91 tests in 79.799s
~/Kount$ coverage report --omit=*/local/*,*/.local/*
  

~/Kount$ coverage  html --omit=*/local/*,*/.local/*