You can receive email or webhook push notifications when an Ethoca or Verifi Alert is issued. This allows you to respond quickly to the alerts in the portal.
-
Log in to the Dispute and Chargeback Management portal.
-
Select Settings.
-
Select Event Notifications.
-
For email notifications, select Email. Add the email addresses and event types you want to receive.
The event type subscriptions are shared with all of the email addresses. You can add and delete the email addresses and event types, and disable or delete everything in email notifications.
-
For webhook push notifications, select Webhook.
-
Enter the webhook URL.
-
Under Headers, select Add +, enter the Header key and Header Value, then select Add.
-
Under Event type subscriptions, select Add +, select the event types, then select Add.
If we are unable to confirm that the webhook was received, we try again up to five times. After the fifth attempt, we will stop trying.
Table: The POST JSON body
|
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
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.
{
"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"
}
]
}
View alerts in the Processing status with the Alerts Actions API. You can pull data to view alerts at any time.
We provide a JSON Web Token (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 <KOUNT_PROVIDED_JWT_TOKEN>'
<KOUNT_PROVIDED_JWT_TOKEN> is different for each environment (QA/Sandbox/Production).
Table: Response body
|
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.
There are 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.
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:
Example: 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: 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: 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 |
{
"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"
}
]
}
{
"actions": [
{
"id": "a424f700-9cdb-482b-8fce-d0c3dad4c97c",
"alertSystem": "CDRN",
"alertType": "DISPUTE",
"amount": "120",
"currency": "USD",
"date": "2021-06-29",
"statusCode": "951",
"action": "resolved"
}
]
}
{
"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": ""
}
]
}
{
"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": ""
}
]
}