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 connection. The credentials for the API connection type requires 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 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”}}
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}]}]"
}
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 | 50 | 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 |
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:
Response Payload Data Element Table
arn |
string |
Acquirer Reference Number (ARN) associated with the request |
events |
list of JSON objects { requestID 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 |
matched |
boolean |
True when merchant transaction data was matched to the partner request False when not able to match transaction data |
customerName |
string |
Customer Name from transaction |
partnerID |
string |
Ethoca: Ethoca ID Verifi: CDRN Case ID |
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.
Frequently Asked Questions
Are there alternative methods to send data to Kount?
If required by your company to send data to Kount by a method other than the API (such as SFTP), contact your Customer Success Manager to discuss potential options.
Comments
0 comments
Article is closed for comments.