Skip to main content
Submit a request
×

How to Integrate the Kount Dispute and Chargeback Management APIs

  • Updated

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

Uploaded files must have unique names and the initial transaction data MUST include sales in the title. Any subsequent file that includes additional data for existing transactions MUST include update in the title.

Example file name: merchantName_sales01312021

 

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, RDR)

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, RDR
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.

 

Verifi eventTypes

ORDER_INQUIRY is when we have been asked to return additional seller data to the Visa Issuer. When we match to your transaction data we send all the data we can. When we do not match to a transaction we send default data.

DISPUTE is a pre-dispute alert that gives you 72 hours to issue a customer refund to avoid a chargeback.

CANCEL is a notification that requires any subsequent billing for that noted account number to be blocked or suspended.

RDR is a VISA pre-dispute alert that the transaction was eligible for Rapid Dispute Resolution.   Refund rules are merchant defined and will be executed by the acquirer and no refund should be processed by the seller for Accepted transactions.

DISPUTE_NOTICE is a VISA notification of a chargeback.  No refund should be processed. For best practices we recommend suspending subsequent billings for the card holder.

FRAUD_NOTICE is a VISA notification of a confirmed fraud event by the cardholder. No refund should be processed.  For best practices we recommend suspending subsequent billings for the card holder.

 

Ethoca eventTypes

ETHOCA_DISPUTE is a pre-dispute alert that gives you 24 hours to issue a customer refund to avoid a chargeback.

ETHOCA_FRAUD is an alert that gives you 24 hours to issue the customer refund to avoid a chargeback.

 

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"
        }
    ]
}

Below is a sample payload from a RDR eventType:

{
     "transactionCurrency": "USD",
     "transactionDateTime": "2020-01-29T20:10:00Z",
     "transactionAmount": 4171,
     "descriptor": "Home Store",
     "merchantOrderID": "1261127",
     "arn": "24248097501900421061244",
     "accountNumber": "435600xxxxxx8999",
     "transactionID": "452657290750164",
     "events": [
        {
            "eventDateTime": "2021-02-05T20:40:59Z",
            "requestID": "b35fcd48-f185-43bd-8719-044d64a4cfcb",
            "eventType": "RDR"
        }
     ]
}

 

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"
    }
  ]
}

Related articles

Can’t find what you’re looking for?
Submit a Ticket
Contact Us
+1.866.919.2167