Receive Alerts from Kount
As part of the 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.
Specify which eventType you want to subscribe to before we enable them.
Note: If we are unable to confirm that the webhook was received, we will try again (up to five times). After the fifth attempt, we will stop trying.
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
View alerts in the Processing status with the Kount Alerts Actions API. You can pull data to view alerts at any time.
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
Response Table
The response body includes the following fields:
|
|
|
|
|
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"
}
]
}