Kissht · KE D/ d ,EK>K'z ^K>hd/KE^ Wsd >d î ì î W E/E^h> EdZ Z ^ ^ Z K ZK W Z > DhD / ð ì ì ì í î µ P µ í U î ì í ó µ Z } Ç W < v D Z

Version 20.0 Kissht Merchant Integration Document

0 | K i s s h t

ONEMI TECHNOLOGY SOLUTIONS PVT LTD 202 PENINSULA CENTRE DR S S RAO ROAD PAREL MUMBAI 400012

August 1, 2017

Authored by: Karan Mehta

Merchant API Manual

Merchant Integration Document Version 20.0


1 | K i s s h t

Table of Contents 1. Introduction .................................................................................................................................... 2

1.1 Target Audience and Pre-Requisites ......................................................................................... 2

1.2 Terminology ............................................................................................................................. 2

1.3 Objective of this document ...................................................................................................... 2

2. Integration with Existing Merchant Site ........................................................................................... 3

2.1 Kissht Test & Production Environments .................................................................................... 3

2.2 Obtaining the Merchant Id, Site Key, Secret Key from the Merchant Portal ............................. 3

2.3 Integrating the Kissht Payment Option ..................................................................................... 4

2.4 Passing User Information to Kissht ........................................................................................... 4

2.5 User Information Fields ............................................................................................................ 4

3. Verifying the Status of the Transaction .......................................................................................... 10

3.1 Client Redirect to the Merchant: ............................................................................................ 10

3.2 Real Time Verification of the Status of the Transaction .......................................................... 11

3.3 WebHooks for Transaction Status Updates .................................................................................. 12

4. Modifying Order Details ................................................................................................................. 14


2 | K i s s h t

1. Introduction

Kissht provides online merchants and marketplaces the opportunity to offer their customers the ability to avail instant loans in-order to pay for online goods and services on their websites through its Kissht platform. The Kissht platform is easy to integrate on merchant website and provides customer a seamless experience in availing financing. The entire process for the customer takes less than 90 seconds.

1.1 Target Audience and Pre-Requisites This is a technical document that is targeted at software professionals who are working in the technology domain, and are interested in incorporating the Kissht Instant Credit Facility as a payment method into their existing application.

Readers must be fully familiar with following:

1. Consuming REST Endpoints 2. Parsing JSON Data 3. Composing and Executing Authenticated and Secure POST Requests over SSL

1.2 Terminology Kissht: Kissht is the provider of the platform for obtaining instant personal loans to make payments for online goods and services.

Merchant: Merchant is an online seller of goods or services, who wishes to integrate with Kissht to provide the option of Instant Personal Loans on his website.

Customer: Customer is the end user who wishes to purchase goods or services from the merchant and intends to pay for it using an instant personal loan obtained from Kissht.

1.3 Objective of this document This document provides Kissht Merchant API specifications. It contains details including API data format, protocol, and security specifications.


3 | K i s s h t

2. Integration with Existing Merchant Site

2.1 Kissht Test & Production Environments

Kissht test and production environments are separate. Merchants need an active Kissht Merchant Account to use the test environment and production environment. Merchants will have to log in to their Merchant Panel and get the API credentials for using these environments. All transactions initiated by the merchant on our test environment are not processed. Test environment is strictly for testing the request and response functions. After successfully testing the integration, merchant can move to the production environment by changing the Base URL.

Test Enviroment Base URL : https://www.test.kissht.com/

Production Environment Base URL : https://kissht.com/

2.2 Obtaining the Merchant Id, Site Key, Secret Key from the Merchant Portal

Each Merchant has access to the Kissht Merchant Portal, where he will be required to register the site URL where the Payment Option with Kissht will need to be displayed.

The merchant will have to register on the Merchant Portal at https://www.test.kissht.com/merchant

After signing up, the merchant account will be activated by Kissht once all the legal procedures are completed.

The Merchant Account will automatically be upgraded to the Live server once testing procedures have been completed and verified by Kissht.

Upon logging into the Merchant Portal, the user will be able to access a “SITE KEY”, “SECRET KEY” & “MERCHANT ID” which will be used to authenticate the merchant as well as the website URL.

Each key-set is specific to one domain and its subdomains. If the merchant plans to use the payment option across different websites, he will need to register all the URLS and obtain site keys specific to each domain.


4 | K i s s h t

2.3 Integrating the Kissht Payment Option The sample code for Kissht integration will be provided in a separate Merchant Kit in the platform of your choice. The merchant kit has all the implementation details regarding encryption of the data as well as decryption of the response.

2.4 Passing User Information to Kissht

The Merchant needs to pass certain information regarding the user to Kissht in order for Kissht to determine the eligibility of the user. Please refer the sample code in the language of your preference to understand how the data is to be shared to Kissht.

The Endpoint for handoff of customer data is as follows :

https://www.test.kissht.com/api/apihandler/fastloan

https:// kissht.com/api/apihandler/fastloan

2.5 User Information Fields Merchant must send the following parameters to the Kissht for initiating the transaction and loading the Kissht Application Form.

Field Name Field Purpose Mandatory? Validation

order_id

Order ID generated by the Merchant as per their Systems YES

Alphanumber, upto 50 characters

transaction_amount Total Cart Value YES Numeric, Upto 2 decimal places

user_verified_email Customer Email Address YES Email Validation

user_verified_mobile Customer Mobile Number YES

Mobile Validation, Should not begin with 0, 10 characters, should not


5 | K i s s h t

include +91 etc

first_name Customer First Name YES Alphabets upto 50 characters

last_name Customer Last Name YES Alphabets upto 50 characters

sitekey SiteKey available on Kissht Merchant Panel YES

alphanumeric, generated by Kissht

merchant_id Merchant ID available on Kissht Merchant Panel YES

numberic, generated by Kissht

redirect_url

User will be redirected here after Successful Transaction YES

MUST BE URL ENCODED; URL Validation, 200 characters max

cancel_url

User will be redirected here after Failed Transaction YES

MUST BE URL ENCODED; URL Validation, 200 characters max

billing_address YES AlphaNumeric String

billing_address_2 YES AlphaNumeric String

billing_city YES AlphaNumeric String

billing_state YES AlphaNumeric String

billing_pincode YES PIN Code Validation

billing_country YES AlphaNumeric String

billing_tel YES Numeric String

billing_email YES Email Validation

billing_name YES Alphabets upto 100 characters

shipping_address_1 YES AlphaNumeric String

shipping_address_2 YES AlphaNumeric String

shipping_city YES AlphaNumeric String

shipping_pincode YES PIN Code Validation


6 | K i s s h t

shipping_state YES AlphaNumeric String

shipping_country YES AlphaNumeric String

SKU_list

List of Products along with Price, Category and Description YES

JSON Encoded, upto 5000 characters

customer_since NO mm/yyyy Format

number_of_cancels

Total number of transactions cancelled by customer in the last 6 months NO numeric

moratorium_period No on months of Moratorium Period NO numeric

is_moratorium_loan

Whether this loan is eligible for a Moratorium Period NO Boolean

number_of_txns_6_months

Total number of transactions performed by customer in the last 6 months NO numeric

ratio_card_payments Ratio of the transactions paid using card payment NO

Numeric, Upto 2 decimal places

ratio_net_payments Ratio of the transactions paid using net banking NO


ratio_cod_payments

Ratio of the transactions paid using cash on delivery NO


number_of_returns

Total number of transactions returned by customer in the last 6 months NO numeric

transaction_average_value

Average ticket size of the transactions performed by customer NO


disable_cc_emi

Don't enable the Credit Card EMI option for this Transaction NO Boolean


7 | K i s s h t

disable_fast_loan Don't enable the Fast Loan option for this Transaction NO Boolean

disable_full_payment

Don't enable the Full Payment option for this Transaction NO Boolean

disable_dc_emi

Don't enable the Debit Card EMI option for this Transaction NO Boolean

minimum_downpayment_percentage

This transaction should require minimum downpayment as a percentage of transaction amount NO


SKU DETAILS ARE SENT IN JSON ENCODED FORMAT

SKU List Details

SKU_description MANDATORY

SKU_code MANDATORY

SKU_price MANDATORY

SKU_category MANDATORY

SKU_sub_category OPTIONAL

SKU_mrp OPTIONAL

SKU_image_url OPTIONAL

EXAMPLE :

[{ "SKU_code": "CYD-PLRGT", "SKU_price": "71499.00", "SKU_category": "Appliances", "SKU_sub_category": "Refriegerators", "SKU_mrp": "79999.00", "SKU_image_url ": "https://www.ecommerce.com/images/products/image1.jpg", "SKU_description": "Samsung 762L two door refrigerator" },


8 | K i s s h t

{ "SKU_code": "CYD-PLRG-BT", "SKU_price": "11499.00", "SKU_category": "Home", "SKU_sub_category": "Dining", "SKU_description": "46 Piece Dining Set by Croal" }]


9 | K i s s h t

Sample Display Form Visible to the Customer

The data provided by the merchant will be pre-populated into the customer application form, saving him the trouble of providing redundant information and making the work-flow as seamless as possible.


10 | K i s s h t

3. Verifying the Status of the Transaction

3.1 Client Redirect to the Merchant: Upon successful completion of the transaction, the user will be redirected to the redirect URL as specified in the transaction parameters. The following parameters will be passed as POST parameters to inform the merchant regarding the status of the transaction:

Name Description

FB_TXN_ID Internal Kissht Transaction ID to uniquely identify each transaction.

MERCHANT_ORDER_ID This ID is used by merchants to identify the order. This will be passed back as was initially specified by the merchant.

LOAN_STATUS Status of the Loan Transaction. Values Enumerated below.

ENC_DATA The data provided : FB_TXN_ID, MERCHANT_ORDER_ID & LOAN_STATUS encrypted using the secret key specific for this merchant. This will allow the Merchant to verify the authenticity of the payload.

Possible Values for LOAN_STATUS:

Value Description

DENIED_1 The transaction was denied due to the customer not meeting the basic eligibility criteria for Kissht loan. This will be applicable when a customer is denied by the automated logic during the Payment Workflow itself.

COND_APPROVED The transaction has been conditionally approved, based on the information provided by the customer. Upon thorough verification of the details, the status will change to either DENIED or FINAL_APPROVED. The merchant is requested not to dispatch items or to render services until the status remains in the COND_APPROVED status.

FINAL_APPROVED The transaction has been fully approved and has cleared the due diligence process. The merchant can now dispatch the items or provide the services as may be applicable.

DENIED_2 The transaction was denied due to either lack of documentation provided by the customer or due to inability to meet the customer in person at an appropriate location. This is applicable only for transactions that are in the COND_APPROVED State.


11 | K i s s h t

CUST_ABORT The customer aborted the transaction without availing a loan. A loan was not processed for this customer and the order should not be fulfilled.

ORDER_RETURN_REQUESTED

The Merchant has indicated that the Order Has Been returned by the customer. The Kissht team will then close out the Loan and adjust the payments for the merchant and then mark the order with “ORDER_RETURNED”

ORDER_RETURNED The Kissht team has closed out the loan for this item, since the Merchant has indicated that the Order has been returned. The Loan for this transaction is effectively closed.

ORDER_CANCEL_REQUESTED

The Merchant has indicated that the Order Has Been cancelled by the customer. The Kissht team will then close out the Loan and adjust the payments for the merchant and then mark the order with “ORDER_CANCELLED”

ORDER_CANCELED The Kissht team has closed out the loan for this item, since the Merchant has indicated that the Order has been cacelled. The Loan for this transaction is effectively closed.

3.2 Real Time Verification of the Status of the Transaction In order to verify the status of the transaction, you will need to integrate with the Kissht server and authenticate using your merchant ID and your site key.

You can verify the transaction status at the following end point at any time:

https://www.test.kissht.com/api/apihandler/transaction_status

Request Parameters :

Name Description Type (length)

sitekey The SiteKey as provided to the merchant for the specific domain. Alphanumeric (30) Characters allowed: Alphabet (A-Z), (a-z), Numbers,- (hyphen), / (slash), ,_ (underscore)

merchant_id Merchant Id is a unique identifier generated by Kissht for each activated merchant.

Numeric

merchant_order_id Merchant Id is a unique identifier generated by Kissht for each activated merchant.

Alphanumeric (30) Characters allowed: Alphabet (A-Z), (a-z), Numbers,- (hyphen), / (slash), ,_ (underscore)

FB_TXN_ID Internal Kissht Transaction ID to uniquely identify each transaction.

Alphanumeric (30)


12 | K i s s h t

Characters allowed: Alphabet (A-Z), (a-z), Numbers,- (hyphen), / (slash), ,_ (underscore)

3.3 WebHooks for Transaction Status Updates

Webhooks is a service through which you can receive notifications directly to your server when a FastLoan goes through various states in its lifecycle, like COND_APPROVED, DENIED_1, FINAL_APPROVED, DENIED_2 etc. This way you can always be aware of the state of your FastLoan and you can also move to an event driven model of processing FastLoans.

You will need to set the endpoint for your webhook by logging into your merchant panel and clicking on the “Registered Sites” and adding the URL.


13 | K i s s h t

Your url should be able to receive the request and provide a http response code 200 OK. In this case the Webhook call is registered as successful on our end.

Kissht will be sending the callback messages as HTTP POST Request to the url specified. So whenever a FastLoan status is changed for your merchant account, you can receive a callback to your server. In the callback message all the payment details are shared, so you can update your server and process the order as per your business processes.

The callback request POST Parameters are as follows :

[FB_TXN_ID] => GS22343899 [MERCHANT_ORDER_ID] => GS2234 [TRANSACTION_AMOUNT] => 12000 [LOAN_STATUS] => COND_APPROVED [ENC_DATA] => 099d2a5813c568ff73f065cddd20623bf4ecdf024244638213ae02275887515c0c75266933193c6bd3709b74fef7dbb9bae1cf8b8f1821152104982ef803f4f482232c570e81eaaffda8b05eee9c65cc27373547efceb950338f70db2a901019793ebedbeacaa7a44255d9a18f14d6f9 The encrypted data will need to be decrypted using the Merchant’s Secret key to ensure non-repudiation and verifying the integrity of the data.

A sample code in PHP for the WebHook functionality to be implemented on the Merchant End is provided within the Merchant Kit.


14 | K i s s h t

4. Modifying Order Details

Merchants have the option to Modify the Order Amount after a Loan has been Conditionally Approved but not Final Approved. This is usually helpful in the case when a part of the order has been cancelled or is out of stock. Merchants have to provide a new Order Value and a Modification Reason. The Modification Reason is useful for communication with the End User. The new order value has to be necessarily less than the original order value.

The order modification can be done either for an individual transaction from the admin panel or in the form of a Bulk Excel upload. The template for the Bulk Excel upload can be downloaded from the Admin Panel itself.

Sample for Single Order Modification :

You will be able to see the status of Order Modification Requests in the “Modification Requests” tab in the Merchant Panel. Once the Loan details have been modified from our end, the Modification Request will be marked as completed.


15 | K i s s h t

5. Displaying EMI Offers on the Product Page

In Order to boost customer demand, Merchants can display the EMI offers on the product Page itself. Data has indicated that displaying an EMI Option along with the EMI Amount leads to greater conversion of sales. You can create a plugin which can show offers on the product page in the following manner :

Clicking on Know More :


16 | K i s s h t

We have an API to fetch the offers for each product to be displayed on the Product Page :

Sample Request : GET Headers: data – Sent in an encrypted JSON Format {

“site_key:SFSFSF878FSD8FY”, “secret_key: JHGJHFGS6FTR”

} Header: Array { key:data, site_key:SFSFSF878FSD8FY } URI : “/api/v1/merchantoffer/{merchant_id}” Sample Response: Json Array { "status":true,"msg":{"s1b1":{"data":[{"offer_id":"78","offer_name":"saurabh_demo_v1_1 _1","offer_description":"","offer_promo_text":"Saurabh_demo_v1_1_1","offer_short_text" :"Saurabh_demo_v1_1_1","offer_long_text":"Saurabh_demo_v1_1_1","is_moratorium_all owed":"NO","offer_type":"normal","bullet_loan_days":"0","credit_bac.. }


17 | K i s s h t

6. API to Check Pincode for Kissht Availability

Kissht currently services most major Indian cities and several Tier-2 cities. While we are always expanding the list of pincodes we do currently service, we provide the merchants an easy method to check whether EMI option will be available to the customer.

Using the API, the merchant can programmatically display the Kissht payment option on the checkout page determined by the pincode provided by the user for the shipping address.

API:

POST Method

https://www.test.kissht.com/api/v2/pincodes/is_supported

Parameters :

Key:pincode

Value: 6 digit Pincode (example 400012)

7. Codes 5.1 Response Code

Response Code Description

101 Invalid Credentials

102 Success

103 Failed

104 Cancelled

105 Loan Applied

106 Server Timeout

107 Quickloan Lead Received

5.2 Error Code

Error Code Error Description

01 Missing Mandatory Parameters

02 Invalid Merchant


18 | K i s s h t

03 Invalid Channel

04 Invalid Bank Code

05 Invalid Tenure

06 Invalid Promo code

07 Sigature Mismatch

08 Invalid Amount

09 Invalid Payment Option

10 Invalid Cashback Option

11 Cashback Option is not enabled


19 | K i s s h t

5.3 Channel Codes

Channel Code Description

CC Credit Card

DC Debit Card

NB Net banking

LN Loan

CD HDFC CDL

BL Bajaj EMI

5.4 Tenure Codes

Code Tenure Month

00 0

01 3

02 6

03 9

04 12

05 15

06 18

07 24


20 | K i s s h t

5.5 Bank Codes

Code Bank Name

01 AMEX

02 Axis Bank

03 Citibank

04 HDFC Bank

05 HSBC

06 ICICI Bank

07 IndusInd

08 Kotak Mahindra

09 RBL

10 SBI

11 Standard Chartered

Documents

Kissht · KE D/ d ,EK>K'z ^K>hd/KE^ Wsd >d î ì î W E/E^h> EdZ Z ^ ^ Z K ZK W Z > DhD / ð ì ì ì í î µ P µ í U î ì í ó µ Z } Ç W < v D Z