How to Integrate the Kount Near Real-Time Chargeback Prevention APIs

This guide provides a high-level overview of the integration points and required flows for integrating with the Kount Near Real-Time Chargeback Prevention (NRTCP) APIs. During the integration process, Kount’s Solution Engineers provide direct support for your development staff to facilitate quick, accurate responses to any integration questions that might arise.

Steps to integrate:

To begin using NRTCP, you must provide the following:

• 6 months of previous transaction data, minimum (The more data provided, the better)
• Merchant Identification Numbers (MIDs)
• Acquirer BIN
• Order number
• Transaction date and time
• Transaction amount
• Basic description

The data you provide is used to match records with Visa. Sending more than the minimum data set allows us to better match the Visa data. In many cases, the customer cart information is filled in at this point so we might have additional data points such as all items purchased, item IDs, amounts, and taxes. Providing customer emails, customer names, a link to the item, and shipping information (if it’s a shipped product) all increase the chance of preventing the chargeback. For digital goods, video games, or online memberships, similar data (account username, last logins, download times, play times, etc) can also be used.

The goal is to attain enough information to trigger a memory in the consumer that they did make the purchase or that a family member might have completed the transaction.

 

Upload Data to Kount

Upload your transactions data to Kount via Kount’s upload API or sFTP.

Upload API

Sandbox Endpoint - http://api-sandbox.kount.com/kff/uploads

Production Endpoint - https://api.Kount.com/kff/uploads
    Method: Post

    Header: Authorization: Bearer <token>
    Header: Content-Type: application/json
    Body: {"transactions": "<valid json object or array>"}

If you are sending multiple transactions, you must provide a JSON array, not multiple JSON objects. Data Definitions are defined in the table below.

 

Sending transactions with sFTP

Kount provides you credentials to upload your transactions data via sFTP. You can upload a .csv file or json objects.

You can upload transactions data and refund data that match the elements defined in our standard data elements.

 

This table provides the standard data elements that can be included in the transactions data.

Name	Type	Additional Info	Size
Kountclientid	string	Your Kount client ID	50
Authstatus	string	Can be D (decline) or A (authorized)	50
kountordernumber	string	Kount order number	50
siteID	string		250
customerID	String	The customerID for the merchant	250
paymentinformation	object
	avsMatch:string	"True" or "False"	10
	cardBin:string	First 6 of card used for purchase	6
	billingName:string	Name on card used for purchase	100
	billingState:string	Billing state from card used for purchase	50
	billingAddress2:string	Address line 2 from card used for purchase	50
	last4:string	Last 4 on card used for purchase	4
	billingCountry:string	Country on card used for purchase	50
	postalCode:string	Zip Code from card used for purchase	50
	billingAddress1:string	Street Address from card used for purchase	150
	billingCity:string	City from card used for purchase	50
additionaltransactiondata	object
	deviceType:string	PC, iPhone, Android Phone, etc	50
	browserOrAppDesc:string	For a web browser use IE, Chrome, Firefox etc or for other methods such as video game clients use XYZ Game Client or other description consumer will recognize	50
customeremailaddress	string	Customer email address	50
customername	string	Customer Name	100
cvvvalidatedatpurchase	string	"True" or "False"	10
deviceid	string	Device ID	50
ipaddress	string	IP Address	50
ordercurrency	string	ISO 4217Alpha 3 ( “USD” )	10
orderdatetime	string	ISO 8601 format YYYY-MM-DDThh:mm:ssZ
ordernumber	string	A reference number by which the merchant can identify the transaction. This should be the ID that is sent to the acquirer.	50
ordertotal	int	(Total amount of the order)*100	11
Shoppingcart	Array of object
	itemID:int	What the item is known as in the merchant store	50
	quantity:int	Quantity of item purchased
	itemName:string	ID that identifies the product to the merchant, like a SKU.	100
	itemDescription:string	Item description	250
	itemType:string	Type of item such as ebook, virtual currency, season pass, etc.	200
	price:double	Price of item in order currency described above. Example $44.09 would be 4409

 

Receive Data from Kount

Receive Near Real Time Chargeback Prevention (NRTCP) data from Kount via Kount’s upload API or sFTP.

 

Outbound API/Webhook: 

To get webhook push notifications for events, customers need to provide:

1. 1. 1. API url
      2. Required header key value pairs. Authentication (API key, etc.) will be covered in the headers
      3. A list of event types customer wants to receive data about. The JSON element “eventType” is included in the response, and will indicate one of the following corresponding data elements:

• • • • • Dispute
        • Dispute_Notice
        • Cancel
        • Fraud_Notice

 

Sample POST body schema:

{

  "arn": {"1346791346789"},

  "cardAcceptorID": "1346789",

  "merchantOrderID": "20000000",

  "transactionAmount": "10.00",

  "transactionCurrency": "USD",

  "transactionDataTime": "2020-09-05T12:00:00Z",

  "transactionID": "13465798123456789",

  "acquirerBin": "423456",

  "events": [

    {

      "requestId": "13456khjk123",

      "eventType": "Dispute",

      "eventDateTime": "2020-09-12T12:00:00Z",

      "disputeCode": "10.4"

    }

  ]

}

Outbound sFTP Files:

To receive sFTP files for events, customers need to provide site credentials to Kount. Here are samples of the reports a customer may choose to receive:

 

Inquiry Report (OI Inquiries)

requestID	issuerTrxID	requestDateTime	merchantOrderNumber	orderTotal	currencyISO3	billingType	transactionAmount_USD
198	300071263573808	9/30/2020 10:32:00	ORDER_1000	123.45	959	1	123.45

*NOTE: billingType 1 indicates a notification, billingType 3 indicates a deflection.

Fraud Report (Fraud Notifications)

requestID	issuerTrxID	requestDateTime	merchantOrderNumber	orderTotal	currencyISO3	reasonCode	transactionAmount_USD
197	300071263573808	9/30/20 22:24:00	ORDER_1000	39.99	959	10	39.99

 

Chargeback Report (Dispute Notifications)

requestID	issuerTrxID	requestDateTime	merchantOrderNumber	orderTotal	currencyISO3	reasonCode	transactionAmount_USD
196	300071263573808	9/30/20 12:38:00	ORDER_1000	39.99	959	10	39.99

 

CDRN Cancel Report (CDRN Cancel Alerts)

requestID	issuerTrxID	requestDateTime	merchantOrderNumber	orderTotal	currencyISO3	reasonCode	transactionAmount_USD
195	300071263573808	9/30/20 10:02:00	eba066b4c7f478f6943dc2026363c4a4	39.99	840	75	39.99

 

CDRN Dispute Report (CDRN Dispute Alerts)

requestID	issuerTrxID	requestDateTime	merchantOrderNumber	orderTotal	currencyISO3	reasonCode	transactionAmount_USD
194	300071263573808	9/30/20 10:02:00	eba066b4c7f478f6943dc2026363c4a4	39.99	840	75	39.99