Receiving and Responding to Alerts in Dispute and Chargeback Management

September 04, 2024 17:40

You can receive and respond to Verifi or Ethoca alerts in Dispute and Chargeback Management by authenticating with our API endpoint.

API Authentication

Kount provides you an API secret through an encrypted email.
Send an HTTP POST with the API secret to the Sandbox or Production Auth Server URL.
You then receive a returned JSON payload that includes a special bearer token, as well as an expiration date provided — within a few seconds — in the form of an expires_in attribute.

Note

If you do not refresh the special bearer token before it expires, the call to the API fails and a 401 Unauthorized message displays. Most tokens issued by https://login.kount.com expire after 20 minutes. Avoid unnecessary calls to the /token endpoint by writing customer applications to factor token expiration. Make sure to check whether a token is expired before requesting a new one. Excessive calls to the /token endpoint might result in rate limiting.

The API varies depending on if you call the Sandbox or Production system. The values are:

Environment	Auth Server URL	API URL
Sandbox	https://login.kount.com/oauth2/ausdppkujzCPQuIrY357/v1/token	https://api-sandbox.kount.com
Production	https://login.kount.com/oauth2/ausdppksgrbyM0abp357/v1/token	https://api.kount.com

Note

For HTTP POST samples, refer to Sending Data for Dispute and Chargeback Management.

Verifi dispute response

This response is sent when Kount receives a Verifi dispute.

{
 "transactionCurrency": "USD",
 "transactionDateTime": "2023-06-02T00:00:00Z",
 "transactionAmount": 9.95,
 "descriptor": "company_name",
 "authorizationCode": "9YJPQ7",
 "merchantOrderID": "INV-062023-630",
 "arn": "02703403153768460426363",
 "accountNumber": "535215xxxxxx3404",
 "transactionID": "1612231599281",
 "events": [
  {
   "disputeCode": "41",
   "eventDateTime": "2023-06-06T00:00:00Z",
   "requestID": "93a360ca-4612-4fb1-9267-a9bba46c8ce1",
   "eventType": "DISPUTE"
  }
 ]
}

POST JSON Body Elements

Any fields in the JSON payload that are empty or null are not included for the transaction. For example, the ARN field will not be included when the ARN is not available. Refer to the following table for a list of POST JSON body elements:

Element	Type	Description
arn	string	Acquirer Reference Number (ARN) associated with the request
cardAcceptorID	string	Card Acceptor ID
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
authorizationCode	string	The Acquirer authorization code for the transaction
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

Note

We are continuously working on adding new fields to the payload to assist with matching the correct transaction. Please enable your configuration to accommodate any new desired fields, as necessary.

Pull alerts in Processing status

View alerts in the Processing status with the Alerts Actions API. You can pull data to view alerts at any time.

Pull alerts in Processing status

View alerts in the Processing status with the Alerts Actions API. You can pull data to view alerts at any time.

Alerts Actions API Request

Alerts Actions API URL

Sandbox endpoint: https://api-sandbox.kount.com/kff/alerts/actions

Alerts Actions API HTTP Method

Method: GET

Alerts Actions API Authentication

We provide a JWT token to be passed into a header of each request to authenticate as a valid request.

Alerts Actions API 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>'

<TEMPORTARY_JWT_TOKEN_RETRIEVED_FROM_AUTH_ENDPOINT> is different for each environment (sandbox or production).

Alerts Actions API Response

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.

Responding to Alerts

Alert response options include an automated response from Kount to the partner that sent the alert, manually entered responses in the Dispute and Chargeback Management portal, or in an API response sent to Kount.

Verifi Alerts

Dispute alerts can only have the action of Resolved or Declined with the Status Code that applies.

Cancel alerts can only have the action of Cancelled or Declined with the Status Code that applies. Valid Declined Status Codes for Cancel Alerts are: 900, 901, 902, 940, 953, and 955.

If an alert is responded to with a status code that does not match the action, an error will be returned, and the alert may need to be manually responded to in order to prevent a chargeback.

All Verifi alerts must be responded to, and refunded (if resolved), within 72 hours of alert creation date and time.

Ethoca Alerts

Confirmed Fraud alerts can have the actions of stopped, partially_stopped, previously_cancelled, missed, notfound, account_suspended, in_progress, shipper_contacted, or other. Customer Dispute alerts can have the actions of resolved, previously_refunded, unresolved_dispute, notfound, or other.

If an alert is responded to with an action that does not match the alert type, an error is returned, and a new POST must be sent for that alert to receive a response. The refunded response prevents a chargeback.

All Ethoca alerts must be responded to and refunded (when applicable) within 24 hours of alert creation.

Responding to Ethoca or Verifi Alerts with the Alert Action API

When you receive an Alert notification for Ethoca or Verifi, you can submit an action (your response back to Ethoca or Verifi) with the Alert Action API. Initiate a new HTTP call to the following endpoint:

Alerts Actions API URL

Sandbox endpoint: https://api-sandbox.kount.com/kff/alerts/actions

HTTP Method

Method: POST

Example 1. Response body payload example (JSON)

{
       “actions”: array of CDRNAction objects
    }

Example 2. Action Fields Guide

   {
    "actions": [
        {
            "id": "bebf622e-3706-4e21-8707-e2beadb7e5e7",
            "action": "resolved",
            "alertSystem": "Ethoca",
            "alertType": "ETHOCA_FRAUD",
            "refunded": "refunded",
            "amount": 30.00,
            "currency": "USD",
            "date": "2021-06-01",
            "statusCode": "stopped",
            "comments": "Previosly refunded in Verifi"
        },
        {
            "id": "bebf622e-3706-4e21-8707-e2beadb7e5e7",
            "action": "resolved",
            "alertSystem": "CDRN",
            "alertType": "DISPUTE",
            "statusCode": "100"
        }
    ]
}

Table 1. Fields to submit in actions JSON POST

Tag	Verifi	Ethoca	Notes
"id"	Request ID from the Alert	Request ID from the Alert	Required Kount unique identifier provided in the Alert
"action"	Dispute Alerts: resolved, declined Cancel Alerts: cancelled, declined	resolved	Required
"alertSystem"	CDRN	Ethoca	Required
"alertType"	DISPUTE, CANCEL,	ETHOCA_FRAUD, ETHOCA_DISPUTE	Required
"refunded"	N/A	refunded, not refunded, not settled	Optional — required for Ethoca
"amount"	Amount refunded	Amount refunded	Optional — full amount will be used if amount not provided
"currency"	Currency of amount refunded	Currency of amount refunded	Optional — full amount will be used if amount not provided
"date"	date of the refund or cancelation in the format YYYY-MM-DD	Date of the refund or cancellation in the format YYYY-MM-DD	Optional
"status code"	Status code to return with the Action for Verifi Alerts (see table for valid codes)	ETHOCA_FRAUD: stopped, partially_stopped, previously_cancelled, missed, notfound, account_suspended, in_progress, shipper_contacted, other ETHOCA_DISPUTE: resolved, previously_refunded, unresolved_dispute, notfound, other	Required
"comments”	N/A	For alerts with "other" action. 200 characters available for comments.	Optional for Ethoca alerts

Table 2. Verifi Status Codes

Status Code	Action	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

Alerts Actions API URL

Sandbox endpoint: https://api-sandbox.kount.com/kff/alerts/actions

HTTP Method

Method: POST

Alert and Response Payload Examples

Verifi dispute response

This response is sent when Kount receives a Verifi dispute.

{
 "transactionCurrency": "USD",
 "transactionDateTime": "2023-06-02T00:00:00Z",
 "transactionAmount": 9.95,
 "descriptor": "company_name",
 "authorizationCode": "9YJPQ7",
 "merchantOrderID": "INV-062023-630",
 "arn": "02703403153768460426363",
 "accountNumber": "535215xxxxxx3404",
 "transactionID": "1612231599281",
 "events": [
  {
   "disputeCode": "41",
   "eventDateTime": "2023-06-06T00:00:00Z",
   "requestID": "93a360ca-4612-4fb1-9267-a9bba46c8ce1",
   "eventType": "DISPUTE"
  }
 ]
}

Verifi RDR response

This response is sent when Kount receives a Verifi RDR alert.

{
 "arn":"74648933212130944903445”,
 "cardAcceptorID":"3653941d583ef49”,
 "merchantOrderID":"rec-FUErk9t5mbRt4kd",
 "transactionAmount":44,
 "transactionCurrency":"EUR",
 "transactionDateTime":"2023-07-30T00:00:00Z",
 "transactionID":"483211493874899",
 "accountNumber":"453942xxxxxx2429",
 "authorizationCode":"056587",
 "outcome":"Accepted",
 "matched":true,
 "customerName":"Claudia Hutch”,
 "events":[
  {
   "requestID":"8b20e55a-2090-4663-a632-7cc537016eae",
   "eventType":"RDR",
   "eventDateTime":"2023-08-05T07:50:35Z",
   "disputeCode":"10.4"
  }
 ],
 "brand”:”kount.online",
 "rdrRuleName":"Accept All"
}

Verifi order insight inquiry response

This response is sent when Kount receives a Verifi order insight inquiry.

{ 
 "cardAcceptorID": "100814",
 "transactionCurrency": "USD",
 "transactionDateTime": "2023-06-02T16:22:01Z",
 "authorizationCode": "XL2OKK",
 "merchantOrderID": "INV-062023-637",
 "accountNumber": "424242******4242",
 "transactionID": "1YGtXrwpL2vr5MwXiSfZiszC2Q",
 "customerName": "Vladimir Witting",
 "acqMid": "500000",
 "transactionAmount": 86.95,
 "matched": true,
 "arn": "24388863153768460426851",
 "events": [
  {
   "eventDateTime": "2023-06-06T21:50:01Z",
   "requestID":"a92b610e-85d0-4e81-91f3-1bb522341621",
   "eventType": "ORDER_INQUIRY"
  }
 ]
}

Verifi dispute notice response

This response is sent when Kount receives a Verifi dispute notice.

{
 "transactionCurrency": "USD",
 "transactionDateTime": "2023-06-02T16:22:01Z",
 "transactionAmount": 86.95,
 "descriptor": "MERCHANT",
 "authorizationCode": "7FULIY",
 "accountNumber": "523215******3404",
 "transactionID": "12345684",
 "events": [
  {
   "eventDateTime": "2023-06-06T21:50:01Z",
   "requestID": "6e801087-e408-4048-ab48-f00e7bc04e0c",
   "eventType": "DISPUTE_NOTICE"
  }
 ]
}

Ethoca dispute response

This response is sent when Kount receives an Ethoca dispute alert.

{
 "transactionCurrency": "USD",
 "transactionDateTime": "2023-06-02T16:22:01Z",
 "transactionAmount": 8.95,
 "descriptor": "MERCHANT",
 "authorizationCode": "81ILQ8",
 "accountNumber": "424242******4242",
 "transactionID": "12345678",
 "events": [
  {
   "eventDateTime": "2023-06-06T21:50:01Z",
   "requestID": "6e801087-e408-4048-ab48-f1007bc04e0a",
   "eventType": "ETHOCA_DISPUTE"
  }
 ]
}

Ethoca fraud response

This response is sent when Kount receives an Ethoca fraud alert.

 {
  "transactionCurrency": "USD",
  "transactionDateTime": "2023-06-02T16:22:01Z",
  "transactionAmount": 86.95,
  "descriptor": "MERCHANT",
  "authorizationCode": "XZ1QEG",
  "accountNumber": "424242******4242",
  "transactionID": "12345681",
  "events": [
   {
    "eventDateTime": "2023-06-06T21:50:01Z",
    "requestID": "6e801087-e408-4048-ab48-f00e0bc44e0c",
    "eventType": "ETHOCA_FRAUD"
   }
 ]
}

Ethoca fraud notice response

This response is sent when Kount receives an Ethoca fraud notice.

 {
  "transactionCurrency": "USD",
  "transactionDateTime": "2023-06-02T16:22:01Z",
  "transactionAmount": 86.95,
  "descriptor": "MERCHANT",
  "authorizationCode": "GPI7ER",
  "accountNumber": "424242******4242",
  "transactionID": "12345682",
  "events": [
   {
    "eventDateTime": "2023-06-06T21:50:01Z",
    "requestID": "6e801087-e408-4048-ab48-f10e7bc44e6c",
    "eventType": "FRAUD_NOTICE"
   }
 ]
}

Was this article helpful?

0 out of 2 found this helpful