Quick Links

Receiving and Responding to Alerts in Chargeback Management

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

Generate an API Key

In Kount 360, after you have activated your organization, you can generate API keys to send data securely to Equifax. Only users with the Owner role permissions can generate, delete, or edit API keys.

Caution

You must have an initialized client before you can create an API key.

  1. Sign in to Kount 360.

    There are two integration environments: sandbox and production. Only integrate into our sandbox environment if you are integrating a pre-production environment without production data for testing.

  2. Select Admin, and then Product Configuration.

  3. In System Settings, select API Keys.

    All initialized clients display.

  4. For the client you want to create an API key, select Generate API Key.

    The new API key is generated. A prompt displays with the ability to copy the API key and add a description.

  5. Copy the API key, and then store it in a secure location.

    Note

    The API key is not provided again. You must store it in a secure location for future reference. If the API key is compromised or lost, create a new API key and delete the compromised one.

  6. Enter a description detailing the store used for the API key, and then select Confirm.

API keys are organized under each client on the API Keys page. Expand the client to view your API keys, the descriptions, and when client details were created.

Create a Bearer Token

After you have provisioned your API credentials in the portal, retrieve a temporary bearer token to authenticate calls to the Kount 360 API. Provide the API key in an HTTP POST to a specific login.equifax.com URL.

With a successful exchange, the returned JSON provides a special bearer token, which is the access_token property. The exchange also provides an expiration date, the expires_in property, provided in seconds until expiration. The API to retrieve the bearer token depends on if you are calling the sandbox or production environment.

The values are:

Sandbox

Auth Server URL:

https://login-uat.equifax.com/as/token

API Service Host:

https://api-sandbox.kount.com

Production

Auth Server URL:

https://login.equifax.com/as/token

API Service Host:

https://api.kount.com

After obtaining the bearer token, use it to authenticate requests to the Kount 360 API. Include the token in the Authorization header of your HTTP API request, prefixed with Bearer {bearer token}.

To prevent authentication issues, refresh the token before it expires. Tokens issued by login.equifax.com expire after 20 minutes, but client credentials remain valid unless revoked. Minimize calls to the /token endpoint by implementing token expiration handling in your customer applications. Always check if a token has expired before requesting a new one, as excessive calls to the /token endpoint could result in rate limiting.

Bash

Go

Python

TypeScript

Verifi CDRN alert response

This response is sent when we receive a Verifi CDRN alert.

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

Alerts Actions API Request

Alerts Actions API URL

Sandbox API endpoint

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

Production API endpoint

https://api.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 <EQUIFAX_PROVIDED_JWT_TOKEN>'

<TEMPORARY_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 us to the partner that sent the alert, manually entered responses in Chargeback Management, or in an API response sent to us.

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 API endpoint

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

Production API endpoint

https://api.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 Equifax 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


Alert and Response Payload Examples

Verifi CDRN alert response

This response is sent when we receive a Verifi CDRN alert.

{
 "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 we receive a Verifi RDR alert.

message GetEventNoticesResponse {
  repeated EventResponse alerts = 1;
}

message EventDetail {
  string requestID = "1234567890";
  string eventType = "RDR";
  string eventDateTime = "2025-08-05T07:50:35Z";
  string disputeCode = "10.4";
}

message EventResponse {
  repeated EventDetail events = 1;
  string arn = "24388863153768460426851";
  string cardAcceptorID = "100814";
  string descriptor = "company_name";
  string merchantID = "123456";
  string merchantOrderID = "INV-062023-637";
  double transactionAmount = 86.95;
  string transactionCurrency = "USD";
  string transactionDateTime = "2025-08-05T07:50:35Z";
  string transactionID = "12345684";
  string accountNumber = "523215******3404";
  string acquirerBin = "12345678";
  string authorizationCode = "056587";
}

Verifi order insight inquiry response

This response is sent when we receive 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 Visa chargeback notification response

This response is sent when we receive a Verifi Visa chargeback 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 alert response

This response is sent when we receive 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 alert response

This response is sent when we receive 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"
   }
 ]
}

Verifi Visa fraud notification response

This response is sent when we receive a Verifi Visa 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 4 found this helpful