Receiving and Responding to Alerts in Dispute and Chargeback Management

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

API Authentication

  1. Kount provides you an API secret through an encrypted email.

  2. Send an HTTP POST with the API secret to the Sandbox or Production Auth Server URL.

  3. 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. CDRNAction Object

    {
    
        “id”: string, required
        “action”: string, required
    
        “alertSystem”: string, required
    
        “alertType”: string, required
    
        “refunded”: string, optional (recommended for Ethoca) 
        “amount”: string, optional
        “currency”: string, optional
        “date”: string, optional 
        “statusCode”: string, required
    
        “comments”: string, optional 
    }

Table 1. Data to submit in 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

Recommended with all Ethoca responses to avoid chargebacks.

"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