Quick Links

Chargeback Management Integration Guide

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—Analyze, Fight, and Prevent—to address both criminal and "friendly" fraud while maintaining customer account health.

Chargeback Management uses the Evaluate Order, Update Order, and Batch Update Reversals from the Orders API collection to evaluate transactions. These REST API calls can be used for Chargeback Management only, or in tandem with Payments Fraud.

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.

Chargeback Management includes the following products and services from Verifi (Visa) and Ethoca (Mastercard):

  • Order Validation: A customer shares order data with Kount 360. The platform matches incoming order validation inquiries from Verifi and Ethoca to order data. This information supplies bank agents with additional data to deflect the customer from raising a dispute.

  • Compelling Evidence 3.0 (CE3): A step-up to Verifi's product that is similar to Order Validation for 10.4 (unauthorized use-of-card) disputes. Kount 360 shares eligible order data with incoming dispute cases from Verifi. If eligibility is met, liability for the dispute is transferred from the merchant to the issuing bank.

  • Cardholder Dispute Resolution Network (CDRN) and Ethoca Alert: An early-warning notification of an incoming cardholder dispute. Merchants have 24-72 hours to resolve the issue with the customer. This crucial window gives your business the chance to issue a refund voluntarily, preventing a hard chargeback against your merchant processing ratio and saving you from costly chargeback penalties.

  • Rapid Dispute Resolution (RDR): A fully automated system from Verifi that instantly refunds a dispute based on custom rules that are defined during onboarding.

Chargeback Management flow

Review the Chargeback Management data flow before beginning your integration to become familiar with the system.

Diagram that shows the Chargeback Management data flow.
  1. Order collection

    1. Collect order data: The customer captures order data, such as items purchased and order total.

    2. Collect device data (Highly recommended): If a customer is using Compelling Evidence 3.0 (CE3.0), we highly recommend enabling Device Data Collection (DDC) to improve deflection performance.

  2. Evaluate Order (POST): The customer sends order data and device data (if collected) to Kount 360 after an order has been created or from a scheduled job (real-time, hourly, or daily).

    Note

    Scheduled jobs must be created by the merchant.

  3. Updates (Optional)

    1. Update Order (PATCH): The customer can update additional order details—such as shipping information (tracking or confirmations) or authorization details (Aquierer Reference Number, or ARN)—that are useful for deflecting or fighting a chargeback.

    2. Batch Reversal Update (PATCH): The customer can update additional order details, such as refunds or chargeback reasons. If Payments Fraud is being used, this information can help build out buyer personas and why they dispute transactions, allowing clients to stop fraudsters from entering their buying process.

  4. Webhook listener: Kount 360 sends webhook notifications to the customer when an event is received and created in the Kount 360 backend.

    These events are:

    • Order Validation

    • CE3.0

    • Cardholder Dispute Resolution Network (CDRN)

    • Ethoca Alert

    • Rapid Dispute Resolution (RDR)

    • Inform

    If an alert is matched to an order, the webhook provides this information. This allows a customer to automatically begin the refund/resolution process in their Customer Relationship Management (CRM) system.

  5. Alert Action (POST): The customer can leverage the webhook notifications to trigger the alert action API to refund/resolve the alert in Kount 360. Kount 360 then forwards this notification to the issuing banks.

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: https://app-sandbox.kount.com and https://app.kount.com. Only integrate into the 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.

    Note

    You must be the organization Owner to access System Settings.

  4. For the client you want to create an API key for, 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 viewable after closing the prompt. 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 for the store or environment that will be connected to 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 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.

Caution

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

Bash

Go

Python

TypeScript

Integration scenarios

Depending on your use case, your integration needs can vary. We provide instructions for customers that use both Payments Fraud and Chargeback Management, recurring billing, and Chargeback Management only.

Standard Transaction Request Properties

The following table contains the required and optional properties to include when sending a transaction request to the Evaluate Orders API.

The more 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.

Add the Device Data Collector (highly recommended)

Adding the Device Data Collector (DDC) is highly recommended as it provides improved performance for Compelling Evidence 3.0 (CE3.0).

CE3.0 uses five fields from historical card-not-present transactions to shift liability from the merchant to the issuing bank during the dispute process.

CE3.0 reviews:

  • Device ID

  • Device Fingerprint

  • IP Address

  • Account ID

  • Delivery Address.

Using the DDC solution can fingerprint a device and provide a merchant with Device Fingerprint and Device ID. This evidence improves matching performance for CE3.0.

Device Data Collector implementation

The Device Data Collector (DDC) 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:

Kount_360_DDC_Flow_V2__1_.svg
  1. Generate Session ID: Generates a session ID and provides it to the DDC SDK.

  2. Device Data Collector SDK collects and sends device data: The DDC sends the collected device data to Kount 360.

  3. 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 DDC.

  4. 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.

  5. 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.

Configure Webhooks

You can configure webhooks within Kount 360 to be informed when a Chargeback Management event is created. Use webhooks to feed internal reporting and/or as an indicator to send the Alert Action API.

Go to Webhooks in Chargeback Management to learn about webhook event types.

To configure webhooks in Kount 360, go to Manage Webhooks.

Respond to Ethoca or Verifi Alerts with the Alerts Actions API

When you receive an Alert notification for Ethoca or Verifi, you can send your response back to Ethoca or Verifi with the Alert Action API. Initiate a new HTTP call to the Alerts Actions endpoint for the appropriate environment:

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

Current API Reference

Example Request Payload

This example shows a request payload for submitting alert actions to Ethoca and Verifi. Include one action object for each alert response.

   {
    "actions": [
        {
            "id": "bebf622e-3706-4e21-8707-e2beadb7e5e7",
            "statusCode": "REFUNDED"
        }
    ]
}

This table describes the fields that can be included in each action object.

Field

Required

Notes

id

Required

Equifax-unique identifier provided in the Alert.

status code

Required

Status code to return with the action for alerts (see table for valid codes).

Valid status codes are listed in the Valid Status Code Values table. Each status code represents a complete alert outcome. Unlike the legacy Alerts Actions API, the current version does not require a separate action value to indicate the alert disposition.

Status Code

Description

REFUNDED

Full Refund Issued: A full refund was issued on this transaction or voided the transaction prior to settlement.

PARTIALLY_REFUNDED

Refund Previously Issued: The transaction was refunded prior to receiving the alert.

NOT_REFUNDED

No Refund Issued: Did not issue a refund; allow to advance to a chargeback.

PREVIOUSLY_REFUNDED

Refund Previously Issued: The transaction was refunded prior to receiving the alert.

DUPLICATE

Duplicate Alert: The transaction has already received another alert from another provider.

DISPUTE_RECEIVED

Already a Chargeback: A chargeback was issued on this transaction prior to receiving the alert.

TRANSACTION_DECLINED

Declined Transaction/Failed Authorization: The transaction was declined; no refund was required.

TRANSACTION_HAS_3DS

3DS Authentication: This transaction was authenticated by 3D Secure; no refund was required.

TRANSACTION_NOT_FOUND

Not Found: The transaction could not be found in CRM or gateway.

REFUND_FAILED

Unable to Issue Refund: The refund was declined for this transaction.

Was this article helpful?
0 out of 0 found this helpful