How to Receive and Respond to Alerts in the Kount Dispute and Chargeback Management Solution

Receive Alerts from Kount

As part of Kount's Dispute and Chargeback Management (DCM) solution, you can receive email notifications when an Ethoca or Verifi Alert is issued. This allows you to timely respond to the alerts in the Kount DCM portal. If you are not already a Dispute and Chargeback Management customer using the portal, contact your Kount representative to set up access and provide a demo.

Outbound API/Webhook

To receive webhook push notifications for events, provide the API URL, required header authentication API key value pairs, and a list of the event type data. The JSON element eventType must be 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)

The POST JSON body contains

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

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

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.

NOTE: Kount is 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.

Sample payload from a (Verifi Dispute) 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"
        }
    ]
}

 

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

Responding to Alerts

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.

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 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.

Action the partner alert through Kount - (POST method)

When you receive an Alert notification for Ethoca or Verifi, you can submit an action (your response back to Ethoca or Verifi) with Kount’s alert action endpoint. Initiate a new http call to the following endpoint:

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

Response body payload example (JSON)

{

    “actions”: array of CDRNAction objects 

}

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 
}

Data to submit in JSON post

 

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 cancelation 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

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

Sample Alert and Response Payloads

Dispute Alert sent to merchant endpoint

{
  "arn": "25697213397332887195465",
  "cardAcceptorID": "1346789",
  "merchantOrderID": "eba066b4c7f478f6943dc2026363c4a4",

  "authorizationCode": "74390",
  "transactionAmount": "200",
  "transactionCurrency": "USD",
  "transactionDataTime": "2021-06-25T00:00:00Z",
  "transactionID": "1624867684189",
  "acquirerBin": "378282",
  "events": [
    {
      "requestId": "a424f700-9cdb-482b-8fce-d0c3dad4c97c",
      "eventType": "DISPUTE",
      "eventDateTime": "2021-06-28T08:09:32Z",
      "disputeCode": "41"
    }
  ]
}

Dispute Alert response sent to Kount

{
 "actions": [
    {
      "id": "a424f700-9cdb-482b-8fce-d0c3dad4c97c",

      "alertSystem": "CDRN",

      "alertType": "DISPUTE",
      "amount": "120",
      "currency": "USD",
      "date": "2021-06-29",
      "statusCode": "951",
      "action": "resolved"
    }
  ]
}

Confirmed Fraud Alert sent to merchant endpoint

{
  "arn": "25697213397332887195465",
  "cardAcceptorID": "1346789",
  "merchantOrderID": "eba066b4c7f478f6943dc2026363c4a4",

  "authorizationCode": "34259",
  "transactionAmount": "1500.99",
  "transactionCurrency": "USD",
  "transactionDataTime": "2021-01-09T21:13:32.000Z",
  "transactionID": "1624867684189",
  "acquirerBin": "499161",
  "events": [
    {
      "requestId": "c30fed69-fb4f-415d-9987-c1194d0a569c",
      "eventType": "ETHOCA_FRAUD",
      "eventDateTime": "2021-06-28T08:09:32Z",
      "disputeCode": ""
    }
  ]
}

Ethoca Fraud Alert response sent to Kount

{
 "actions": [
    {
      "id": "c30fed69-fb4f-415d-9987-c1194d0a569c",

      "alertSystem": "Ethoca",

      "alertType": "Ethoca_Fraud",
      "date": "2021-06-28T23:59:59.999Z",
      "statusCode": "stopped",
      "action": "resolved",

      "refunded": "not settled"
    }
 ]
}

Ethoca Dispute Alert sent to merchant endpoint

{
  "arn": "25697213397332887195465",
  "cardAcceptorID": "1346789",
  "merchantOrderID": "eba066b4c7f478f6943dc2026363c4a4",

  "authorizationCode": "12552",
  "transactionAmount": "17099.5",
  "transactionCurrency": "USD",
  "transactionDataTime": "2020-09-01T16:00:00.000Z",
  "transactionID": "1624867684189",
  "acquirerBin": "423234",
  "events": [
    {
      "requestId": "2291161f-8c35-48f3-a801-9d16a8462f9a",
      "eventType": "ETHOCA_DISPUTE",
      "eventDateTime": "2021-06-28T08:09:32Z ",
      "disputeCode": ""
    }
  ]
}

Customer Dispute Alert response sent to Kount

{
 "actions": [
    {
      "id": "2291161f-8c35-48f3-a801-9d16a8462f9a ",

      "alertSystem": "Ethoca",

      "alertType": "ETHOCA_DISPUTE",
      "date": "2021-06-28T23:59:59.999Z",
      "statusCode": "unresolved_dispute",
      "action": "resolved",

      "refunded": "refunded"
    }
 ]
}
Was this article helpful?
0 out of 0 found this helpful