Chargeback Management provides an end-to-end, post-authorization solution designed to protect customer revenue by preventing, intercepting, and winning payment disputes. The solution follows a strategic framework—Prevent, Fight, and Analyze—to address both criminal and "friendly" fraud while maintaining customer account health.
Chargeback Management uses our Orders API to evaluate transactions. This REST API is also used by our Payments Fraud solution. As such, you must tailor your requests by using attributes specific to Chargeback Management.
Note
This document is for new customers that have not previously integrated with our legacy Chargeback product. For customers that migrated to Kount 360 from our legacy product, go to Sending Data for Chargeback Management or Receiving and Responding to Alerts in Chargeback Management for information about integration and data submission.
Optionally, you can integrate with our Device Data Collection (DDC) service to enhance your match and deflection rates. While Chargeback Management is already compliant with Visa Compelling Evidence 3.0 (CE3.0), adding the DDC provides another core transaction data element with the device session ID.
Note
If you are already integrated with our Payments Fraud or Account Protection products, you do not need to implement the DDC again.
The Device Data Collector gathers information from a customer’s device by running client-side scripts and then sends that data to Equifax. This passive analysis conceals the Kount 360 interaction with the customer and does not affect the customer’s experience.
The flow for device data collection follows this pattern:
-
Generate Session ID: Generates a session ID and provides it to the Device Data Collector SDK.
-
Device Data Collector SDK collects and sends device data: The Device Data Collector sends the collected device data to Kount 360.
-
Submit event data with session ID to your server: When the event data (the order, login, or new account opening data) gets submitted to your server, include the session ID that was passed to the Device Data Collector.
-
Send event data with session ID to Kount 360: Pass the session ID in the call to Kount 360, along with the rest of the event data.
-
Associate device data and event data by matching the session ID: Kount 360 associates the device data and the event data by using the session ID that was passed to Kount 360.
For detailed instructions, use our guided Device Data Collector Content generator or follow the steps in the Native iOS and Android SDKs article.
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.
The Orders API is a REST HTTPS endpoint that uses OAuth 2.0 for authentication. This API is used by both the Chargeback Management and Payments Fraud solutions.
Sandbox Endpoint
https://api-sandbox.kount.com/commerce/v2/orders&riskInquiry=false
Production Endpoint
https://api.kount.com/commerce/v2/orders&riskInquiry=false
Method: POST
Header Authorization: Bearer token
Header Content-Type: application/json
Body: Refer to the Standard Chargeback Management Request Properties.
The following table contains the required and optional properties to include when sending a transaction request.
The more recommended and optional properties you include in the request, the better your matching and deflection rates are.
For more information about data submission, the importance of comprehensive data, and expanded details about the required JSON properties, go to Orders API: Best Practices.
After sending an order to the Orders API, you might need to update the order by providing the result of payment authorization or providing an order ID. Updating the Order does not perform another risk inquiry. Updating an order is ensures that the system is able to detect and prevent fraud.
The Orders API provides the Order Update and Update Orders' Chargeback and Refunds endpoints to update an order.
-
Order Update is used to update specific data properties of an order, such as the authorization status details and customer-provided order ID.
-
Update Orders’ Chargebacks and Refunds is used to provide updates to the order’s lifecycle, such as whether it resulted in a chargeback or refund.
The orders update is primarily used in a pre-authorization workflow after the order has been sent to the payment processor for authorization and you have received the result. Calling the endpoint lets Equifax know the result of the authorization for model training, reporting, and order management. Refer to the following chart for the pre-authorization workflow:
The Orders API is a REST HTTPS endpoint that uses OAuth 2.0 for authentication. Refer to Authentication to learn how to acquire the bearer token. The {Order Id} is a value that would have been retrieved from the order.OrderId in the POST /orders response when the order was originally sent to Equifax.
Sandbox Endpoint:
https://api-sandbox.kount.com/commerce/v2/orders/{ORDER ID}
Production Endpoint:
https://api.kount.com/commerce/v2/orders/{ORDER ID}
Method: PATCH
Header Authentication: Bearer <token>
Header Content Type: application/json
Body: Refer to the properties table.
In order to protect credit or debit card numbers, also known as the Primary Account Number (PAN), we provide you with a tokenization algorithm to create a hash value. This serves as a one-way cryptographic representation of the sensitive payment information.
By tokenizing the payment information, it enables us to utilize the data in our machine learning models and other fraud-prevention systems while ensuring anonymity and complying with the Payment Card Industry Data Security Standards (PCI-DSS).
During the integration process, your assigned Solutions Engineer or Integration Engineer provides you with an algorithm and salt to generate a hash value from the Primary Account Number (PAN).
-
Tokenize the payment information into a hash value.
-
Pass the hash value to the Orders API in the
transactions.payment.paymentTokenproperty.
Important!: If you only have the BIN and/or last 4 digits of the PAN, do not pass the masked value into the transactions.payment.paymentToken property. With a masked PAN, all of the values except the first six digits (BIN) and last 4 digits of the number are replaced. The replaced values become X's, asterisks, or another character. For example: 401288XXXXXX1881.
Instead, pass the BIN and the last 4 digits into the following properties, and omit the transactions.payment.paymentToken property:
-
transactions.payment.bin -
transactions.payment.last4
The IDs are identical and includes all properties. A request sent from a customer has varying IDs and might not include all properties.
The endpoint to update orders’ chargebacks and refunds is used for successful orders that result in a chargeback or refund, which could happen weeks or months later. Calling the endpoint improves model training and makes the events available in reporting and order workflow management.
The endpoint takes an array of orders, so you can update multiple orders at a time.
The Orders Batch Update Chargeback/Refund Request API is a REST HTTPS endpoint that uses OAuth 2.0 for authentication. Refer to Creating a Bearer Token to acquire the bearer token. The {Kount Order Id} is a value that would have been retrieved from the order.kountOrderId in the POST /orders response when the order was originally sent to Equifax.
Sandbox Endpoint:
https://api-sandbox.kount.com/commerce/v2/orders:batchUpdateReversals
Production Endpoint:
https://api.kount.com/commerce/v2/orders:batchUpdateReversals
Method: PATCH
Header Authorization: Bearer <token>
Header Content Type: application/json
Body: Refer to the properties table.
The properties in the request can only be used at different times and can only be selected as refund, a chargeback, or both — both cannot be unselected. You can only delete the chargeback or the refund, but not both at the same time. For example:
-
isChargeback,isRefund, or both can be true; both cannot be false. -
If an order already has a refund and
isChargebackis passed with a value of true, the refund is removed and the chargeback added. If a refund is added to an order with a refund present, the refund is removed and the refund added. -
chargeback.reasonCodeshould only be present ifisChargebackis true. -
cardTypeshould only be present ifisChargebackis true.
The reversalsUpdates.chargeback.cardType value must match the Card Type value to allow the reversalsUpdates.chargeback.reasonCode property to have a value in the Reason Code column.
{
"reversalsUpdates": [
{
"orderId": "string",
"chargeback": {
"isChargeback": true,
"transactionId": "string",
"reasonCode": "string",
"cardType": "string"
},
"refund": {
"isRefund": true,
"transactionId": "string",
"dateTime": "string",
"amount": 0,
"currency": "string",
"gatewayReceipt": "string"
},
"fraudReportType": "NONE"
}
]
}
If the endpoint response updates are successful, the only property received is an errors property containing an empty array. Since the request input is an array, if there are errors, the errors property will contain an array, and each error will include a orderId property that correlates to the input order that resulted in an error.
{
"errors": [
{
"orderId": "7VQSXX7KHFK5J94X",
"error": "7VQSXX7KHFK5J94X transaction update cannot delete both chargeback and refund"
}
]
}