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

This guide details the integration process for 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.

Integration Guide Overview:

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

Since 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. If customer cart information is available, it can provide additional data points to better match your records to help prevent chargebacks.

Typical data points to provide along with the minimum data set include:

• All items purchased during a transaction
• Item IDs
• Taxes paid
• Amounts
• Customer emails
• Customer names
• A link to the item
• Shipping information

Additional data points to consider specifically when working with video games or online memberships include:

• Account username
• Last log in
• Download times
• Play times

The goal is to attain enough information that can be used to trigger a memory in the consumer  that confirms the purchase - or confirms that a family member might have completed the transaction.

 

Send Data to Kount

Send transaction data to Kount through the Kount API or through a SSH File Transfer Protocol (SFTP) connection. The credentials for both connection types require a unique login specific to your company. The login information is provided to you by your Kount Customer Service Manager during your initial integration. If you would like to use the API or SFTP and do not have your company credentials, contact your Kount representative.

Specifications for the Kount API

Endpoints:

Sandbox  - https://api-sandbox.kount.com/kff/uploads

Production  - https://api.Kount.com/kff/uploads

Method:  Post
Header Authorization:  Bearer <token>
Header Content-Type:  application/json
Body:  {"transactions": {“type” : “string”}}

NOTE: All data sent to Kount via the upload API must be in a JSON string format that is capable of parsing back to JSON. See the table under Standard Transaction Data Elements for additional support.

Specifications for uploading data via SFTP

SFTP Production Hostname:  ff.sftp.kount.com

SFTP Sandbox Hostname:  ff.sftp.sandbox13.kount.com

Transaction and refund data can be uploaded to Kount via SFTP in either CSV or JSON form. Your Kount provided credentials for the SFTP are the same for the sandbox and production environments. All data element types sent via SFTP MUST follow the naming convention defined in the Standard Transaction Data Elements table below. If there is not a verbatim match for an element name during transmission, the data stops loading and the upload fails.

 

Standard Transaction Data Elements (include in the transaction 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 (for internal Kount use)	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
invoicenumber	string	A reference number by which the customer can identify the transaction.	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
authcode	string	Authorization code provided to authorize the purchase	50
ARN	string	Acquirer Reference Number	23

 

Receive Data from Kount

Receive NRTCP data from Kount via the API or an SFTP connection. The table below details the data elements provided in these reports.

Name	Definition
requestID	Unique Kount identifier for each inquiry/alert
issuerTrxID	Transaction ID from the issuer
requestDateTime	Date request was received
MerchantOrderNumber	Merchant order number provided in the request
orderTotal	Total amount of the order received in the request
currency	The currency of the transaction received in the request in ISO 3
billingType	In the Inquiry Report, it is used to determine if the request has been deflected or not (1=deflection, 3=Chargeback occurred and is not a deflection)
transactionAmount	Transaction amount referenced by the case

 

Outbound API/Webhook: 

To get webhook push notifications for events, you must provide the following to Kount:

1. API URL
2. Required header key value pairs. Authentication (API key, etc.) is covered in the headers.
3. A list of the event type data the customer wants to receive. The JSON element eventType is included in the response, and can be one of the following.

Verifi Events (ORDER_INQUIRY, DISPUTE, DISPUTE_NOTICE, CANCEL, FRAUD_NOTICE)

Ethoca Events (ETHOCA_FRAUD, ETHOCA_DISPUTE)

The POST JSON body contains:

Element	Type	Description
arn	string	Acquirer Reference Number (ARN) associated with the request
cardAcceptorID	string	Card Acceptor ID (Not currently available, will add when available)
merchantOrderID	string	Merchant's Order ID associated with the request
transactionAmount	number	Transaction Amount referenced in the request
transactionCurrency	string	The currency of the transaction received in the request in ISO 3
transactionDateTime	string	Date of the transaction
transactionID	string	Transaction ID from the Issuer
accountNumber	string	Masked Payment Account Number in the following format: NNNNNNxxxxxxNNNN
descriptor	string	Billing Descriptor associated with the transaction
eventType	string	Type of Request Verifi: INQUIRY, DISPUTE, DISPUTE_NOTICE, CANCEL, FRAUD_NOTICE Ethoca: ETHOCA_FRAUD, ETHOCA_DISPUTE
eventDateTime	string	Date the request was received
disputeCode	string	Case Reason Code
requestID	string	Unique identifier for the transaction. This can be used to respond to Alerts via API

Any fields in the JSON payload that are empty or null are not included for that transaction. For example, the arn field will not be included when the ARN is not available.

Additional fields can be included at any time.

 

Below is a sample payload from a DISPUTE eventType:

{
    "transactionCurrency": "USD",
    "transactionDateTime": "2021-02-01T00:00:00Z",
    "transactionAmount": 707.25,
    "descriptor": "FraudPVP    *",
    "merchantOrderID": "1826003090",
    "arn": "66231111111111111122292",
    "accountNumber": "422602xxxxxx1234",
    "transactionID": "1612231599281",
    "events": [
        {
            "disputeCode": "41",
            "eventDateTime": "2021-02-02T02:07:33Z",
            "requestID": "93a360ca-4612-4fb1-9267-a9bba46c8ce1",
            "eventType": "DISPUTE"
        }
    ]
}

Below is a sample payload from a ETHOCA_DISPUTE eventType:

{
    "transactionCurrency": "USD",
    "transactionDateTime": "2020-12-01T12:30:00Z",
    "transactionAmount": 300.55,
    "descriptor": "KOUNTQA06MERCHANT",
    "accountNumber": "928292******1111",
    "transactionID": "12345678",
    "events": [
        {
            "eventDateTime": "2021-02-02T21:50:01Z",
            "requestID": "6e801087-e408-4048-ab48-f10e7bc44e6a",
            "eventType": "ETHOCA_DISPUTE"
        }
    ]
}

Below is a sample payload from a Verifi INQUIRY eventType:

{
    "transactionCurrency": "USD",
    "transactionDateTime": "2020-01-29T20:10:00Z",
    "transactionAmount": 12345,
    "descriptor": "THE_ELECTRONICS_STORE",
    "merchantOrderID": "ORDER_1000",
    "arn": "9862277678",
    "accountNumber": "435600xxxxxx1234",
    "transactionID": "11111111111111111111",
    "events": [
        {
            "eventDateTime": "2021-02-05T20:40:59Z",
            "requestID": "b35fcd48-f185-43bd-8719-044d64a4cfcb",
            "eventType": "ORDER_INQUIRY"
        }
    ]
}

Outbound SFTP Files:

By using Kount's outbound SFTP, you can receive event reports for Inquiries (OI), Fraud Notifications (CDRN), Dispute Notifications (CDRN), Dispute Alerts (CDRN),  Cancel Alerts (CDRN).

NOTE: To receive event reports via SFTP, you must provide Kount with your site credentials. 

 

Event Report Example Data:

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

 

CDRN Actions via API

Through the NRTCP portal, you can receive and respond to the CDRN Actions, receive email notifications when an Alert is received, or receive and respond via API. Contact your Kount Customer Success Manager to set up the queue
.

Receive CDRN Alerts from Kount

You can receive email notifications when a CDRN Alert is received. This allows you to timely respond to the alerts in the Kount NRTCP portal.

As described in the webhook section of this document, you can receive a webhook push of the data in the alert, and then respond to the alert.

 

Respond to the Alert to Kount (POST)

Response payload:

{

    “actions”: array of CDRNAction objects 

}

CDRNAction object:

{

    “id”: string, required

    “action”: string, required

    “amount”: string, optional

    “currency”: string, optional

    “date”: string, optional 

    “statusCode”: string, required

}

• ID is the Request ID from the Alert
• Action is one of: resolved, declined or cancelled (resolved or declined for a Dispute Alert, cancelled or declined for a Cancel Alert)
• Amount is the amount refunded
• Currency is the three-character code of the currency in ISO 3
• Date is the date of the refund or cancelation in the format YYYY-MM-DD.
• Status Code is the status code to return with the Action (See table for Codes)

 

Status Code	Outcome	Description*
100	RESOLVED	Case Resolved, Credit & Cancellation processed
101	RESOLVED	Case Resolved, Partial Credit & Cancellation processed
102	RESOLVED	Case Resolved, Authorization Cancelled
951	RESOLVED	Transaction Previously credited for Case Amount, no balance remaining
130	CANCELLED	Cancellation processed
900	DECLINED	Unmatched Case - General/Other
901	DECLINED	Unmatched Case - Merchant not Participating
902	DECLINED	Unmatched Case - Unable to locate Original Transaction
940	DECLINED	Duplicate Request
950	DECLINED	Merchant account closed, unable to process Credit
952	DECLINED	Transaction Previously received a Chargeback, no balance remaining
953	DECLINED	Request is outside of eligibility timeframe
954	DECLINED	Transaction 3D Secure authenticated successfully (Verified by Visa/MasterCard SecureCode)
955	DECLINED	Could not honor cancel request
956	DECLINED	Matched, unable to stop order fulfillment
957	DECLINED	Matched, Proceed with Chargeback for resolution

 

 

Sample Alert and Response payloads:

 

Dispute Alert sent to merchant endpoint

{

  "arn": {"1346791346789"},
  "cardAcceptorID": "1346789",
  "merchantOrderID": "20000000",
  "transactionAmount": "10.00",
  "transactionCurrency": "USD",
  "transactionDataTime": "2020-09-05T12:00:00Z",
  "transactionID": "13465798123456789",
  "acquirerBin": "423456",
  "events": [
    {
      "requestId": "6989a395-c2df-40f4-8021-4aa0a3a15fbd ",
      "eventType": "Dispute",
      "eventDateTime": "2020-12-12T12:00:00Z",
      "disputeCode": "10.4"
    }
  ]
}

Dispute Alert response sent to Kount

{
  "actions": [
    {
      "id": "6989a395-c2df-40f4-8021-4aa0a3a15fbd",
      "amount": "10.00",
      "currency": "USD",
      "date": "2020-12-13",
      "statusCode": "100",
      "action": "resolved"
    }
  ]
}