How to Integrate the Kount Dispute and Chargeback Management APIs

To help automate refunds and streamline sending transactional data, Integrate the Kount Dispute and Chargeback Management (DCM) 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 DCM, 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 Kount 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.

Additional data points to provide (along with the minimum data set):

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

Example JSON string to send to Kount:

{
"transactions": "[{\"authStatus\":\"A\",\"kountOrderNumber\":\"DVVN1ZZYU2L7\",\"paymentInformation\":{\"avsMatch\":\"False\",\"cardBin\":\"410045\",\"last4\":\"3847\",\"authCode\":\"3845737\",\"billingName\":\"JOHN DOE\",\"billingAddress1\":\"1005 W Main St\",\"billingAddress2\":\"\",\"billingCity\":\"Boise\",\"billingState\":\"ID\",\"postalCode\":\"83702\",\"billingCountry\":\"USA\"},\"additionalTransactionData\":{\"browserOrAppDesc\":\"Chrome 88.0.4324.182\",\"deviceType\":\"\"},\"customerEmailAddress\":\"john.doe@kount.com\",\"customerName\":\"JOHN DOE\",\"cvvValidatedAtPurchase\":\"False\",\"deviceID\":\"358680B39D5240A8C382A11F2EBC7150\",\"ipAddress\":\"81.233.22.53\",\"orderCurrency\":\"USD\",\"orderDateTime\":\"2021-02-21T12:22:13.000Z\",\"orderNumber\":\"ABC123\",\"orderTotal\":4783,\"shoppingCart\":[{\"itemDescription\":\"BLACK MAC KEYBOARD\",\"itemName\":\"MAC KEYBOARD\",\"quantity\":1,\"itemType\":\"ACCESSORIES\",\"itemID\":\"225\",\"price\":4783}]},{\"kountClientID\":\"999666\",\"authStatus\":\"A\",\"kountOrderNumber\":\"DVVN1ZZYU2L8\",\"paymentInformation\":{\"avsMatch\":\"False\",\"cardBin\":\"410394\",\"last4\":\"3948\",\"billingName\":\"JANE DOE\",\"billingAddress1\":\"1005 W Main St\",\"billingAddress2\":\"\",\"billingCity\":\"Boise\",\"billingState\":\"ID\",\"postalCode\":\"83702\",\"billingCountry\":\"USA\"},\"additionalTransactionData\":{\"deviceType\":\"iPhone 12\"},\"customerEmailAddress\":\"jane.doe@kount.com\",\"customerName\":\"Jane Doe\",\"cvvValidatedAtPurchase\":\"False\",\"deviceID\":\"358680B39D5240A8C382A11F2EBC7151\",\"ipAddress\":\"72.17.122.212\",\"orderCurrency\":\"USD\",\"orderDateTime\":\"2021-02-21T11:25:29.000Z\",\"orderNumber\":\"ABC124\",\"orderTotal\":1812,\"shoppingCart\":[{\"itemDescription\":\"MACHINE LEARNING FOR DUMMIES\",\"itemName\":\"MACHINE LEARNING\",\"quantity\":2,\"itemType\":\"BOOK (PRINTED)\",\"itemID\":\"A34322\",\"price\":906}]}]"
}

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 JSON form. The credentials for the SFTP are provided by Kount and are the same for both 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.

Example JSON to send to Kount:

[
{
"authStatus": "A",
"kountOrderNumber": "DVVN1ZZYU2L7",
"paymentInformation": {
"avsMatch": "False",
"cardBin": "410045",
"last4": "3847",
"authCode": "3845737",
"billingName": "JOHN DOE",
"billingAddress1": "1005 W Main St",
"billingAddress2": "",
"billingCity": "Boise",
"billingState": "ID",
"postalCode": "83702",
"billingCountry": "USA"
},
"additionalTransactionData": {
"browserOrAppDesc": "Chrome 88.0.4324.182",
"deviceType": ""
},
"customerEmailAddress": "john.doe@kount.com",
"customerName": "JOHN DOE",
"cvvValidatedAtPurchase": "False",
"deviceID": "358680B39D5240A8C382A11F2EBC7150",
"ipAddress": "81.233.22.53",
"orderCurrency": "USD",
"orderDateTime": "2021-02-21T12:22:13.000Z",
"orderNumber": "ABC123",
"orderTotal": 4783,
"shoppingCart": [
{
"itemDescription": "BLACK MAC KEYBOARD",
"itemName": "MAC KEYBOARD",
"quantity": 1,
"itemType": "ACCESSORIES",
"itemID": "225",
"price": 4783
}
]
},
{
"kountClientID": "999666",
"authStatus": "A",
"kountOrderNumber": "DVVN1ZZYU2L8",
"paymentInformation": {
"avsMatch": "False",
"cardBin": "410394",
"last4": "3948",
"billingName": "JANE DOE",
"billingAddress1": "1005 W Main St",
"billingAddress2": "",
"billingCity": "Boise",
"billingState": "ID",
"postalCode": "83702",
"billingCountry": "USA"
},
"additionalTransactionData": {
"deviceType": "iPhone 12"
},
"customerEmailAddress": "jane.doe@kount.com",
"customerName": "Jane Doe",
"cvvValidatedAtPurchase": "False",
"deviceID": "358680B39D5240A8C382A11F2EBC7151",
"ipAddress": "72.17.122.212",
"orderCurrency": "USD",
"orderDateTime": "2021-02-21T11:25:29.000Z",
"orderNumber": "ABC124",
"orderTotal": 1812,
"shoppingCart": [
{
"itemDescription": "MACHINE LEARNING FOR DUMMIES",
"itemName": "MACHINE LEARNING",
"quantity": 2,
"itemType": "BOOK (PRINTED)",
"itemID": "A34322",
"price": 906
}
]
}
]

 

Standard Transaction Data Elements (include in the transaction data):

Field	Type	Size	Recommendation	Additional Info
authStatus	string	50	Optional	D (decline) or A (authorized)
customerID	string	250	Optional	Customer ID used by the merchant
paymentInformation	json object
avsMatch	string	10	Optional	Boolean string as "True" or "False"
cardBin	string	6	Recommended	First 6 of card used for purchase
last4	string	100	Recommended	Last 4 on card used for purchase
authCode	string		Optional	Authorization code provided to authorize the purchase
arn	string		Recommended	Acquirer reference number
billingName	string	50	Recommended	Name on card used for purchase
billingAddress1	string	50	Recommended	Street address for card used for purchase
billingAddress2	string	4	Optional	Address line 2 for card used for purchase
billingCity	string	50	Optional	City for card used for purchase
billingState	string	50	Optional	Billing state for card used for purchase
postalCode	string	150	Optional	Zip or postal code for card used for purchase
billingCountry	string	50	Optional	Country for card used for purchase
additionalTransactionData	json object
deviceType	string	50	Optional	PC, iPhone, Android Phone, etc
browserOrAppDesc	string	50	Optional	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
customerEmailAddress	string	50	Recommended	Customer email address
customerName	string	100	Recommended	Customer name
cvvValidatedAtPurchase	string	10	Optional	"True" or "False"
deviceID	string	50	Optional	Device ID
ipAddress	string	50	Optional	IP Address
orderCurrency	string	10	Recommended	ISO 4217Alpha 3 ( “USD” )
orderDateTime	string		Required	ISO 8601 format in UTC time zone: YYYY-MM-DDThh:mm:ssZ
orderNumber	string	50	Required	A reference number by which the merchant can identify the transaction. This should be the ID that is sent to the acquirer.
invoiceNumber	string	50	Optional	A reference number by which the customer can identify the transaction.
orderTotal	int	11	Required	(Total amount of the order)*100 - Example $44.09 would be 4409
shoppingCart	json array of objects
itemID	string	50	Optional	ID that identifies the product to the merchant, like a SKU.
itemType	string	200	Recommended	Type of item such as ebook, virtual currency, season pass, etc.
itemName	string	100	Recommended	What the item is known as in the merchant store
itemDescription	string	250	Recommended	Item description
quantity	int		Optional	Quantity of item purchased
price	int		Optional	(Price of item in order currency) * 100. Example $44.09 would be 4409

 

Outbound API/Webhook: 

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

• API URL
• Required header key value pairs. Authentication (API key, etc.) is covered in the headers.
• 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: ORDER_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 ORDER_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 DCM 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 DCM 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"
    }
  ]
}