Skip to main content
Submit a request
×

How to Integrate the Kount Dispute and Chargeback Management APIs

  • Updated

Integrate the Kount Dispute and Chargeback Management (DCM) APIs to help automate refunds and streamline sending transactional data.

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

You must provide the following to begin using DCM:

  • Six 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 with the upload API must be in a JSON string format that is capable of parsing back to JSON. See the table in the Standard Transaction Data Elements section for additional support.

Example of a 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 with 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 using 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 with SFTP must follow the naming convention defined in the Standard Transaction Data Elements table below. If there is not an exact 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

Receive data from Kount

You must provide the following to Kount to get webhook push notifications for events:

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

POST JSON Body

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.

Pull alerts in Processing status

Get notified when you have alerts in Processing status by pulling data using Kount's Alerts Actions API.

API Request

API URL

QA URL: https://api-qa06.kount.com/kff/alerts/actions
Sandbox URL: https://api-sandbox.kount.com/kff/alerts/actions
Prod URL: https://api.kount.com/kff/alerts/actions

HTTP Method

GET

Authentication

A JSON Web Token (JWT token) needs to be passed into a header of each request to authenticate as a valid request. The JWT token is provided by Kount.

Request Example

Initiate an HTTP GET call to the API endpoints to retrieve the alerts that are currently in processing status.

curl --location --request GET 'https://api.kount.com/kff/alerts/actions' \
--header 'Authorization: Bearer <KOUNT_PROVIDED_JWT_TOKEN>'

<KOUNT_PROVIDED_JWT_TOKEN> is different for each environment (QA/Sandbox/Production).

Response

The response body includes the following fields:

Field

Type

Description

arn

string

Acquirer Reference Number (ARN) associated with the request

events

list of JSON objects

{

requestID string
eventType string
eventDateTime string
disputeCode string

}

requestID: Unique identifier for the transaction. This can be used to respond to Alerts via API

eventType: Type of Request

Verifi: ORDER_INQUIRY, DISPUTE, DISPUTE_NOTICE, CANCEL, FRAUD_NOTICE, RDR

Ethoca: ETHOCA_FRAUD, ETHOCA_DISPUTE

eventDateTime: Date the request was received

disputeCode: Case Reason Code

 

cardAcceptorID

string

Card Acceptor ID (Not currently available, will add when available)

descriptor

string

Billing Descriptor associated with the transaction

merchantID

string

 

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

acquirerBin

string

 

authorizationCode

string

The Acquirer authorization code for the transaction

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

Response Examples

Sample payload for a Verifi Dispute (i.e. DISPUTE eventType):

{
"transactionCurrency": "USD",
"transactionDateTime": "2021-02-01T00:00:00Z",
"transactionAmount": 707.25,
"descriptor": "FraudPVP *",
"authorizationCode": "74390",
"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"
}
]
}

Sample payload from an ETHOCA_DISPUTE eventType:

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

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 72 hours to issue a customer refund to avoid a chargeback.

ETHOCA_FRAUD is an alert that gives you 72 hours to issue the customer refund to avoid a chargeback. You have 72 hours to respond, but to optimize the prevention of receiving a chargeback, we recommend you respond within 24 hours.

Sample payload from a DISPUTE eventType

{
    "transactionCurrency": "USD",
    "transactionDateTime": "2021-02-01T00:00:00Z",
    "transactionAmount": 707.25,
    "descriptor": "FraudPVP    *",

    "authorizationCode": "74390",
    "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"
        }
    ]
}

Sample payload from a ETHOCA_DISPUTE eventType

{
    "transactionCurrency": "USD",
    "transactionDateTime": "2020-12-01T12:30:00Z",
    "transactionAmount": 300.55,
    "descriptor": "KOUNTQA06MERCHANT",

    "authorizationCode": "426A3",
    "accountNumber": "928292******1111",
    "transactionID": "12345678",
    "events": [
        {
            "eventDateTime": "2021-02-02T21:50:01Z",
            "requestID": "6e801087-e408-4048-ab48-f10e7bc44e6a",
            "eventType": "ETHOCA_DISPUTE"
        }
    ]
}

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

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",
     "outcome": "Accepted",
     "events": [
        {
            "eventDateTime": "2021-02-05T20:40:59Z",
            "requestID": "b35fcd48-f185-43bd-8719-044d64a4cfcb",
            "eventType": "RDR"
        }
     ]
}

CDRN Actions with 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)

Kount provides multiple methods for you to receive and respond to Verifi and Ethoca alerts. You can receive alert details through email notifications or via webhook for Alerts.
Alert response options include an automated response from Kount to the partner that sent the alert, entered responses in the Kount DCM portal, or sent a response to the Kount API. Contact your Kount Customer Success Manager to discuss the option best suited for you. For additional support on responding to Alerts, refer to How to Receive and Respond to Alerts in Kount’s Dispute and Chargeback Management Solution.

Related articles

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