How to Integrate the RIS PHP SDK

The Kount RIS PHP SDK provides instructions for:

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

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

To install the Kount RIS PHP SDK, Kount recommends using Composer. Follow the instructions below:

1. Download Composer if not already installed.
2. Go to your project directory. If you do not have one, create a directory and add cd to the code as shown below.
   

   $ mkdir project
   $ cd project

3. To begin installation, enter composer require kount/kount-ris-php-sdk:* on the command line. Replace composer with composer.phar if required. See the example below:

   $ composer require kount/kount-ris-php-sdk:*
   
   # Output: 
   ./composer.json has been created
   Loading composer repositories with package information
   Updating dependencies (including require-dev)
   Package operations: 1 install, 0 updates, 0 removals
     - Installing kount/kount-ris-php-sdk (6.5.0) Downloading: 100%
   Writing lock file
   Generating autoload files

4. Add kount/kount-ris-php-sdk : * in your composer.json and then run composer install.

   $ composer install  
   
   # Output: 
   Loading composer repositories with package information
   Updating dependencies (including require-dev)
   Package operations: 1 install, 0 updates, 0 removals
     - Installing kount/kount-ris-php-sdk (6.5.2): Loading from cache
   Writing lock file
   Generating autoload files

Generating Documentation

If you want to generate documentation in stylized HTML-formatted style, covering all the classes, their methods, and variables you can use phpDocumentor, which is already added for you in the composer.json file.

1. Run the composer install command in the root directory of the PHP-SDK, where the composer.json is located. This creates the vendor folder with all of the packages listed in composer.json, currently phpDocumentor and phpunit with their respective versions.
2. Once you have the phpDocumentor package added to the vendor folder you can generate HTML documentation by executing the following command:

     phpdoc 
     //This will reference the **phpdoc.dist.xml** file in the root of the directory.

   If the command does not work, you can redo it manually by entering the following command:

     vendor/bin/phpdoc -d src/ -t phpdocs/

3. Once the command runs, you can access the newly generated documentation by opening the index.html file found in path-to-phpsdk/sdkphp/phpdocs/index.html in a browser .

Configuring the RIS PHP SDK

The file settings.ini contains basic configuration for the Kount RIS PHP SDK. Please make sure to set all the values appropriately before attempting to make a RIS request. The file is located in the zip SDK package hierarchy at the following path:

 kount-ris-php-sdk/
   --src/
      --settings.ini

Set the following keys to the desired values:

  MERCHANT_ID = 6-digit integer, referenced as MERCHANT_ID in code snippets
  URL = URL for RIS calls
  SITE ID = SITE_ID
  API_KEY = a JWT key used for authentication, in favor of the deprecated certificates
  CONFIG_KEY = an additional configuration key used within the SDK

Custom settings

Custom settings are optional and help you avoid configuring the settings.ini file every time there is an PHP SDK update.

To use custom settings, create your own settings file, and then provide the path to Kount_Ris_Request_Inquiry.

$customPathToSettingsFile = 'absolute-path-to-settings-file/customSettings.ini';
// the settings file can be a .ini file or a .txt file. 
// If you've placed your custom settings file in the root directory of your e-commerce application,
// you'll just need to provide the name of the settings file.
// $customPathToSettingsFile = 'customSettings.ini';

$inquiry = new Kount_Ris_Request_Inquiry(Kount_Util_Khash::createKhash($customPathToSettingsFile ));
// the Inquiry class will initialize an instance of Kount_Util_Khash and provide the absolute path for the settings file and thus receive the custom settings.

If you want to use the default src/settings.ini, you can call the Kount_Ris_Request_Inquiry directly. Do not worry about supplying a null KHASH object as a constructor parameter as it is null-safe and will not cause exceptions or errors.

$inquiry = new Kount_Ris_Request_Inquiry();
// just as valid, uses the default settings.ini file

Making Your First Call

Ensure you have a valid RIS API Key, URL and data to post.

1. Define the settings and validation file Variables.
2. Require the sdk/autoload.php.
3. Create a Kount_Ris_Request_Inquiry() object.
4. Set values of the Inquiry object.
5. Add cart info via the Kount_Ris_Data_CartItem Objects
6. Request the response via inquiry->getResponse();
7. Process the Response object.

<?php
define ('KOUNT_SETTINGS_FILE', __DIR__ . '/settings.ini');
define('KOUNT_VALIDATION_FILE', __DIR__ . '/validate.xml');
require __DIR__ . '/sdk/autoload.php';
$q = new Kount_Ris_Request_Inquiry();
$q->setTotal(1500);
$q->setCardPayment('6011023856853995');
$q->setIpAddress('198.43.122.98');
$q->setMack('Y');
$q->setWebsite('DEFAULT');
$q->setSessionId('10696db6869912470c2c4b6df51bcaac');
$q->setEmail('joe@example.com');
$cart = array();
$cart[] = new Kount_Ris_Data_CartItem('Electronic', 'TV', 'Big TV', 1, 50000);
$q->setCart($cart);
$response = $q->getResponse();
print_r($response);
?>

Autoload the SDK package. This includes all files and classes to your autoloader. This SDK provides an spl_autoload_register() compatible class loader which reduces the need for fragile relative path based require directives within the SDK itself. The autoloader is enabled by including the src/autoload.php script in your code.

<?php
// 1. Autoload the SDK Package. This will include all the files and classes to your autoloader
// Used for composer based installation
require __DIR__ . './vendor/autoload.php';

// Use below for direct download installation
require __DIR__  . '/path-to-Kount-PHP-SDK/src/autoload.php';

Once settings.ini file is in place, proceed with the following:

1. Wrap the code inside of a try-catch block.
2. Create a Kount_Ris_Request_Inquiry object or Kount_Ris_Request_Update object depending on if you are sending an initial request or updating a previous transaction.
3. Call the setters required for the inquiry or update mode (Q is the default for inquiries and U is the default for updates).
4. Call getResponse() on the inquiry or update object. A populated Kount.Ris.Response object will be returned. The Kount_Ris_Response object has many getters for using the RIS data.

Once a successful inquiry is made, incorporate as many additional setters to the object as are available before calling getResponse(). The more data provided in the object, the more accurate the risk assessment.

  <?php

   // RIS request --- requires curl support enabled in PHP
   // php_mbstring support enabled in your php.ini file
  
  // If using Direct Download
  require __DIR__ . 'path-to-sdk/src/autoload.php';

  //  OR

  // If using Composer installation
  require __DIR__ . './vendor/autoload.php';

  // Minimal RIS inquiry example:
  try {
    $inquiry = new Kount_Ris_Request_Inquiry();

    $inquiry->setSessionId('session-id-max-32-chars');
    $inquiry->setPayment('CARD', '4111111111111111');
   
    $inquiry->setTotal(500);
    $inquiry->setEmail('test@kount.com');
    $inquiry->setIpAddress('192.168.0.21');
    $inquiry->setMack('Y');
    $inquiry->setWebsite("DEFAULT");
    $cart = array();
    $cart[] = new Kount_Ris_Data_CartItem("TV", "LZG-123", "32-inch LCD", 1, 129999);
    $inquiry->setCart($cart);
    $inquiry->setAuth('A');
   
    // additional optional setters..
    // setGender value can be either "M" or "F"

    $inquiry->setGender("M");
    $inquiry->setDateOfBirth("2017-03-12");

    $response = $inquiry->getResponse();
    // optional getter
    $warnings = $response->getWarnings();

    print_r($response);

    $score = $response->getScore();
    $auto = $response->getAuto();

  } catch (Exception $e) {
    print_r($e);
    // handle exception
  }

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 is returned with a MODE = E. 

If the DDC 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 Kount SDK all credit card information, by default, uses the KHASH encryption method where the credit card information is irreversibly hashed prior to transmission from the merchant to Kount.

The following encryption options are available.
KHASH Kount proprietary hash used to hash the credit card number before passing it to Kount. The hashing algorithm source code can be found in each one of the SDKs or can be requested from Kount.

PTYP=CARD PENC=KHASH.
Output - BIN + 14 alpha-numeric characters.
Example - 123456A12C34E56G7DFG

MASK Ability to pass the first six and last four of a credit card filled in with XXXs. PENC=MASK is only valid with PTYP=CARD.

PTYP=CARD PENC=MASK
Output BIN + 10 capital “X” characters + Last 4 of credit card.
Example - 123456XXXXXXXXXX7890

Important: The above example value is just for purposes of illustration. The PTOK should be the same length as the original card number. You can use the card number with the first 6 and last 4 numerals present and the rest of the numbers in the card masked by “Xs” but the number of characters must be the same as those of the actual card number.

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

Logging

Logging allows developers to track activities happening inside the code. You could enable logging for Kount SDK from the INI file in src/settings.ini file under the [LOGGING] section.

[LOGGING]
# Specify the logger to use. The default loggers supplied with the Kount RIS
# SDK are NOP (a logger that silently discards all logging), and SIMPLE (a
# simple logger that writes messages to a specified file).
# See the README for more advanced logging configuration information.
LOGGER=SIMPLE

# Logging level for SimpleLogger if it is enabled.
# Acceptable logging levels in order of decreasing severity are FATAL, ERROR,
# WARN, INFO, and DEBUG.
SIMPLE_LOG_LEVEL=INFO

# Specify the file name where the SimpleLogger will log messages to.
SIMPLE_LOG_FILE=Kount-SDK-Ris-PHP.log

# SimpleLogger log path. This is the directory where the log file will be
# located. This directory must have read and write permissions enabled for the
# PHP user. This directory must already exist.
SIMPLE_LOG_PATH=

# Logging variable to configure the logging of client-side timing metrics.
# Default value is OFF. Can be set to ON which will enable the logging when creating a RIS Request to Kount.
SIMPLE_LOG_RIS_METRICS=ON

LOGGER

• Enables logging
• Options: 'SIMPLE' or 'NOP'
  This specifies the logger to use. The default loggers supplied with the Kount RIS SDK are NOP (a logger that silently discards all logging), and SIMPLE (a simple logger that writes messages to a specified file).

SIMPLE_LOG_LEVEL

• Logging levels available for logging
• Options: FATAL, ERROR, WARN, INFO, and DEBUG

SIMPLE_LOG_FILE

• Specifies the file name where the Simplelogger will log messages to.

SIMPLE_LOG_PATH

• SimpleLogger log path. This is the directory where the log file will be located.

SIMPLE_LOG_RIS_METRICS

• Enables logging of client-side timing metrics when creating a RIS request.
• Logging variable to configure the logging of client-side timing metrics. Default value is OFF.
• Options: ON or OFF

Frequently Asked Questions

    <?php 
    
    namespace App\Services; 
    
    use Kount_Ris_Request_Inquiry; 
    use Kount_Ris_Data_CartItem; 
    
    use Kount_Ris_Request_Update; 
    
    use Kount_Util_Khash; 
    
    class KountService 
    { 
        public function inquiry($order) 
        { 
            // Minimal RIS inquiry example: 
            try { 
                $inquiry = new Kount_Ris_Request_Inquiry(); 
                ... 
            } catch (Exception $e) { 
                print_r($e); 
                // handle exception 
            } 
        } 
    }