You can receive and respond to Verifi or Ethoca alerts in Chargeback Management by authenticating with our API endpoint.
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.
-
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.
-
Select Admin, and then Product Configuration.
-
In System Settings, select API Keys.
All initialized clients display.
-
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.
-
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.
-
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.
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.
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"
}
]
}
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.
View alerts in the Processing status with the Alerts Actions API. You can pull data to view alerts at any time.
Sandbox API endpoint
https://api-sandbox.kount.com/kff/alerts/actions
Production API endpoint
https://api.kount.com/kff/alerts/actions
We provide a JWT token to be passed into a header of each request to authenticate as a valid request.
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).
|
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: Ethoca: 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.
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.
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.
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.
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:
Sandbox API endpoint
https://api-sandbox.kount.com/kff/alerts/actions
Production API endpoint
https://api.kount.com/kff/alerts/actions
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 |
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"
}
]
}
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";
}
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"
}
]
}
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"
}
]
}
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"
}
]
}
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"
}
]
}
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"
}
]
}