Dispute and Chargeback Management Integration Guide

May 26, 2023 20:21

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

Send Data to Kount

Send transaction data to Kount through API endpoints. The credentials for the API 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 Customer Success Manager.

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 Standard Transaction Data Elements table for additional information.

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

Standard Transaction Data Elements (include in the transaction data)

Field	Type	Size	Recommendation	Additional Info
authStatus	string	50	Recommended	D (decline) or A (authorized)
customerID	string	250	Recommended	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		Recommended	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	Recommended	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	Recommended	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		Recommended	Quantity of item purchased
price	int		Recommended	(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 from Verifi and Ethoca depending on what the customer wants to receive. The JSON element eventType is included in the response and can be one of the following:

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 Events by Event Type

Request when you have a new event with Kount’s Events Action API. Alerts that require an action and have a status of Processing are returned in a JSON payload with the data they requested.

Specifications for the Kount DCM Events Action API

Endpoints:

Sandbox: https://api-sandbox.kount.com/kff/alerts/notices/{{dayEpoch}}/eventType/DISPUTE
Production: https://api.kount.com/kff/alerts/notices/{{dayEpoch}}/eventType/DISPUTE

Note: The dayEpoch in the DCM Events Action APIs is a Unix timestamp.

HTTP Method: GET

Authentication: Pass the Kount provided JSON Web Token (JWT) into the header of each request to authenticate.

Request Example: Initiate an HTTP GET call to the API endpoints to retrieve a list of all events of the type specified, starting at the epoch time defined. For DISPUTE, CANCEL, ETHOCA_DISPUTE, ETHOCA_FRAUD, only alerts in processing are returned.

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

URL construction: https://api-env.kount.com/kff/alerts/notices/epoch time/eventType/event type

Event types:

ORDER_INQUIRY
FRAUD_NOTICE
CHARGEBACK, DISPUTE_NOTICE
DISPUTE
CANCEL
RDR
ETHOCA_DISPUTE
ETHOCA_FRAUD
ETHOCA_CALLCENTER
ETHOCA_DIGITAL

Response

The response body includes the following fields:

Response Payload Data Element Table

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, CHARGEBACK Ethoca: ETHOCA_FRAUD, ETHOCA_DISPUTE, ETHOCA_CALLCENTER, ETHOCA_DIGITAL
eventDateTime	string	Date the request was received
disputeCode	string	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

eventType	Description
ORDER_INQUIRY	When we have been asked to return additional seller data to the Visa Issuer. When we match your transaction data we send all the data we can. When we do not match a transaction we send default data.
DISPUTE	A pre-dispute alert that gives you 72 hours to issue a customer refund to avoid a chargeback.
CANCEL	A notification that requires any subsequent billing for that noted account number to be blocked or suspended.
RDR	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	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	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

eventType	Description
ETHOCA_DISPUTE	A pre-dispute alert that gives you 72 hours to issue a customer refund to avoid a chargeback.
ETHOCA_FRAUD	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 using the 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 Receive data from Kount, 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 the Kount 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.

Was this article helpful?

1 out of 2 found this helpful