Chargebackhit API Reference

Download OpenAPI specification:Download

Enhance your understanding with our detailed Business Guide.

Support: support@chargebackhit.com

Get started

Chargebackhit provides API that empowers you to process and manage alerts. Chargebackhit APIs accept and return JSON in the HTTP body. You can interact with the APIs directly using your preferred HTTP/REST library or leverage one of ours.

Environment Base URL
Webhook https://api.chargebackhit.com/client-webhook-endpoint
Integration https://api.chargebackhit.com/api/v2/integration
Alerts https://api.chargebackhit.com/api/v2/alerts
MIDs https://api.chargebackhit.com/api/v2/caids
Enrollment https://api.chargebackhit.com/api/v2/import
API changes

Great care is taken to ensure that changes to the APIs do not impact existing integrations. Below are the types of changes considered to be backward-compatible:

  • New fields Inclusion of new, optional request fields or parameters to existing APIs.
  • Response modifications Addition of new fields to existing API responses.
  • HTTP headers Introduction of new, optional HTTP request headers or new HTTP response headers.
  • String length Increase in the length of existing string field values.
  • Identifier format Alteration or removal of prefixes from existing identifiers.
  • Webhook events Introduction of new webhook event types (explicit opt-in required).
  • Webhook schema Addition of new fields to existing webhook event schemas.
  • Versioning Support for API versioning exists, with maintenance of older versions up to a certain point. Advanced notice will be provided for deprecation.
  • Rate limiting Communication regarding changes to rate limiting will occur with at least one month's advance notice.

Event handling in Webhooks

For non-ordered events, adopt practices like temporarily storing webhooks before processing, using Chargebackhit's API for additional data in case of event collisions, and processing events asynchronously to avoid timeout issues.

Authentication

When you sign up for an account, you are given a secret and public API key pair. You authenticate with our API by providing the appropriate key in the request Authorization header. Never share your secret keys. Keep them guarded and secure.

To start accepting alerts, even in the sandbox environment, you need credentials. You can easily find your credentials in the admin panel. The signature value is base64-encoded from the SHA-512 hash function. Apply the merchant's secret key for the encryption key, and use the following string for signature data:
base64encode(sha512(public_key + requestJsonData + public_key))

PHP
Python

JavaScript

GO

Kotlin

To access the detailed information mentioned above, navigate to guide.

Integration

The Chargebackhit provides the following main requests for testing integration:

  • Generate sandbox alert for creating simulated alerts to test and validate integrations in a secure environment
  • Response outcome for effectively communicating chargeback and outcomes while maintaining secure and accurate data sharing.

Both requests offer appropriate response codes to help users identify successful integrations, bad requests, or unauthorized access.

Generate sandbox alert

The primary purpose of this request is to support the testing and validation of Chargebackhit integrations in a controlled environment. The request aims to create simulated alerts for testing purposes. This request ensures secure communication through the use of request signatures and public keys. It contains comprehensive information about the alert.

The request also gathers essential card-related details, such as the card acceptor ID, etc. Additionally, it encompasses merchant details, including their identification, name, and payment descriptor.

header Parameters
signature
string <= 500 characters

Signature of the request allows verifying whether the request is genuine.

public_key
string <= 500 characters

Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json
object

All information about the alert.

object

Associated with the alert transaction data. Used for matching alert to transaction.

object

Information about the MID.

Responses

Request samples

Content type
application/json
{
  • "alert": {
    },
  • "transaction": {
    },
  • "merchant": {
    }
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Validate outcome

The primary purpose of the request is to facilitate effective communication of chargeback and outcomes while ensuring secure and accurate data sharing. The request is designed to process and communicate the outcome of a chargeback.

The request encompasses detailed information about the order, refund, customer, device, transactions, products, and merchant, including various identifiers, dates, amounts, currencies, and contact details. It also covers relevant URLs related to the merchant's policies and terms.

header Parameters
signature
string <= 500 characters

Signature of the request allows verifying whether the request is genuine.

public_key
string <= 500 characters

Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json
outcome
required
string
Enum: "reversed" "previously-reversed" "duplicate" "decline" "reverse-error" … 4 more

Standard required response codes.

  • reversed - the transaction has been refunded after the alert
  • previously-reversed - the transaction was refunded before the alert was issued
  • decline - the transaction associated with the alert was not successful
  • reverse-error - unable to process a refund
  • not-found - the transaction is not found
  • acknowledged - the merchant has decided not to issue any refunds
  • pending - a temporary status that allows you to respond later (recommended within 24h)
  • shipped - a status relevant for physical goods, where goods are already shipped

Upon receiving a webhook alert, the primary task is to promptly provide a valid response using one of the specified outcomes. Only the initial response to the alert is accepted, with the exception when the initial status was set to pending. Once a response is submitted to the provider, subsequent modifications are not permitted.

object

It contains all the information available for the order.

object

The customer information parameters are a set of user identifiers you share alongside your order information.

Array of objects

It contains all the information available for the related transactions.

Array of objects

Additional information of the products that was purchased.

object

Information about the merchant, their contacts, policies, and so on.

Responses

Request samples

Content type
application/json
{
  • "outcome": "reversed",
  • "order": {
    },
  • "customer": {
    },
  • "transactions": [
    ],
  • "products": [
    ],
  • "merchant": {}
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Manage alerts

This section ensures seamless and efficient management of alerts and outcomes within the Chargebackhit.

Update response outcome allows for efficient and secure updates of alert outcomes, ensuring up-to-date information. Get alert by ID facilitates secure access to detailed information about a specific alert, while Alert list enables users to securely and effectively retrieve tailored lists of alerts based on various filtering parameters.

Update response outcome

This request facilitates efficient and secure updating of alert outcomes within the Chargebackhit.

The primary purpose of a request in the Chargebackhit is to update the outcome of a previously submitted alert. This request allows users to provide an updated response outcome for a specific alert identified by its unique identifier (UUID).

path Parameters
id
required
string <uuid>

The identifier.

header Parameters
signature
string <= 500 characters

Signature of the request allows verifying whether the request is genuine.

public_key
string <= 500 characters

Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json
object

It contains all the information available for the order.

outcome
required
string
Enum: "reversed" "previously-reversed" "decline" "reverse-error" "not-found" … 2 more

Standard required response codes.

  • reversed - the transaction has been refunded after the alert
  • previously-reversed - the transaction was refunded before the alert was issued
  • decline - the transaction associated with the alert was not successful
  • reverse-error - unable to process a refund
  • not-found - the transaction is not found
  • acknowledged - the merchant has decided not to issue any refunds
  • shipped - a status relevant for physical goods, where goods are already shipped

Upon receiving a webhook alert, the primary task is to promptly provide a valid response using one of the specified outcomes.

Responses

Request samples

Content type
application/json
{
  • "order": {
    },
  • "outcome": "reversed"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get alert by ID

This request allows users to securely and efficiently access detailed information about a specific alert within the Chargebackhit.

The main purpose of a request in the Chargebackhit is to retrieve detailed information about a specific alert using its unique identifier (UUID). This request allows users to access and review the alert's data, including the alert's details, associated transaction data, and merchant information.

path Parameters
id
required
string <uuid>

The identifier.

header Parameters
signature
string <= 500 characters

Signature of the request allows verifying whether the request is genuine.

public_key
string <= 500 characters

Unique identification that is shared at the moment of registration along with the Private Key.

Responses

Response Schema: application/json
object

The set of parameters used for detailed information about a specific alert.

Response samples

Content type
application/json
{
  • "data": {
    }
}

Retrieve alerts list

This request allows users to securely and effectively retrieve a tailored list of alerts from the Chargebackhit based on a wide range of filtering parameters, ensuring the retrieval of relevant information.

The main purpose of the request in the Chargebackhit is to retrieve a list of alerts based on various filtering parameters, including alert types, outcomes, providers, products, transaction details, and merchant-related information. This request allows users to narrow down and access specific sets of alerts based on their requirements.

Additionally, the request provides pagination options to limit the number of results, helping manage network traffic and improve efficiency.

header Parameters
signature
string <= 500 characters

Signature of the request allows verifying whether the request is genuine.

public_key
string <= 500 characters

Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json
object

The set of parameters used for detailed filtering.

object

Pagination to limit the number of results to help keep network traffic in check.

object

The fields must be indexed to be sorted by them. Thereafter, you can select which parameters to sort by.

Responses

Response Schema: application/json
Array of objects

The set of parameters used for detailed information about a specific alert.

object

Pagination to limit the number of results to help keep network traffic in check.

Request samples

Content type
application/json
{
  • "filter": {
    },
  • "pagination": {
    },
  • "sort": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Webhook

Webhooks are a simple yet powerful way to receive automated notifications from Chargebackhit.

With Webhooks, you can set up your application to receive notifications whenever certain alert events occur and make instant action and applicable responses.

Webhook

In the Chargebackhit webhooks implementation, there are several types of webhooks based on the alert type parameter.

  • Prevent webhooks are triggered when a transaction inquiry occurs that requires an immediate response - sharing transaction details, including order, customer, and product. Prevent represents the inquiry and prevented webhook alert types. Prevent includes Order Insight (OI), Compelling Evidence (CE3.0), and Consumer Clarity (CC). All transaction data can affect and increase a cardholder and issuer experience. The more valid and relevant data provided, the more effective the response can be. In addition to the basic value of Prevent, the Compelling Evidence 3.0 rule aims to deflect fraud disputes when specific conditions are met and valid mandatory fields are transferred. The mandatory fields are highlighted with the CE3.0 badges.

  • Resolve webhooks are triggered when a merchant-directed refund is needed to resolve a potential dispute case or automated pre-dispute resolution has occurred. Merchant-directed refunds are notified by the alert type init-refund (CDRN, ETHOCA), while automated pre-dispute resolutions are notified by the alert type resolved (RDR).

  • Inform webhooks are triggered when a Visa Fraud or Dispute case is filed with alert types fraud-notification or dispute-notification, respectively.

Prevent, Resolve, and Inform webhooks have a unified structure and need to be distinguished by the alert type, with specific products and providers specified in the corresponding fields.

The responses should be in accordance with the specified alert type.

header Parameters
signature
string <= 500 characters

Signature of the request allows verifying whether the request is genuine.

public_key
string <= 500 characters

Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json
object

All information about the alert.

object

Associated with the alert transaction data. Used for matching alert to transaction.

object

Information about the MID.

Responses

Response Schema: application/json
One of
outcome
required
string
Default: "acknowledged"

Standard required response codes.

object

It contains all the information available for the order.

required
object

The customer information parameters are a set of user identifiers you share alongside your order information.

Array of objects

It contains all the information available for the related transactions.

required
Array of objects

Additional information of the products that was purchased.

object

Cardholder/Issuer Experience

Information about the merchant, including their contacts, policies, and more, can be provided as a default during MID enrollment.

If such parameters are not transmitted by the merchant, Chargebackhit will send them by default using the information provided during the onboarding process.

Request samples

Content type
application/json
{
  • "alert": {
    },
  • "transaction": {
    },
  • "merchant": {
    }
}

Response samples

Content type
application/json
Example
{
  • "outcome": "acknowledged",
  • "order": {
    },
  • "customer": {
    },
  • "transactions": [
    ],
  • "products": [
    ],
  • "merchant": {}
}

MIDs

The API offers comprehensive tools for managing and analyzing merchant and CAID data, enabling businesses to assess risk levels, and create holistic risk profiles.

Get merchant

The request enables users to retrieve specific merchant details using a unique identifier id. The response includes the merchant's id, name, and payment descriptor.

path Parameters
id
required
string <uuid>

The identifier.

header Parameters
signature
string <= 500 characters

Signature of the request allows verifying whether the request is genuine.

public_key
string <= 500 characters

Unique identification that is shared at the moment of registration along with the Private Key.

Responses

Response Schema: application/json
object

Information about the MID.

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get merchant list

The request provides list of retrieves merchant lists using flexible filtering, sorting, and pagination options. Users can paginate results, sort by specified fields, and filter by parameters like ids, descriptors, and names. The response contains merchant details and pagination information.

header Parameters
signature
string <= 500 characters

Signature of the request allows verifying whether the request is genuine.

public_key
string <= 500 characters

Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json
object

Pagination to limit the number of results to help keep network traffic in check.

object

The fields must be indexed to be sorted by them. Thereafter, you can select which parameters to sort by.

object

The set of parameters used for detailed filtering.

Responses

Response Schema: application/json
Array of objects

Information about the MID.

object

Pagination to limit the number of results to help keep network traffic in check.

Request samples

Content type
application/json
{
  • "pagination": {
    },
  • "sort": {
    },
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get CAID

The method to retrieve individual CAID (Card Acceptor ID) details using a unique identifier id.

path Parameters
id
required
string <uuid>

The identifier.

query Parameters
include
Array of arrays
Items Value: "caid.activities"

Include the payment this chargeback was issued for.

header Parameters
signature
string <= 500 characters

Signature of the request allows verifying whether the request is genuine.

public_key
string <= 500 characters

Unique identification that is shared at the moment of registration along with the Private Key.

Responses

Response Schema: application/json
object

The set of parameters used for retrieving individual CAID details.

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get CAID list

Leveraging the API's ability to access a list of CAIDs with comprehensive filtering, sorting, and pagination options, the response can gather crucial information such as PSP identifiers, BINs, and merchant details.

header Parameters
signature
string <= 500 characters

Signature of the request allows verifying whether the request is genuine.

public_key
string <= 500 characters

Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json
object

Pagination to limit the number of results to help keep network traffic in check.

object

The fields must be indexed to be sorted by them. Thereafter, you can select which parameters to sort by.

object

The set of parameters used for detailed filtering.

Responses

Response Schema: application/json
Array of objects

The set of parameters used for retrieving individual CAID details.

object

Pagination to limit the number of results to help keep network traffic in check.

Request samples

Content type
application/json
{
  • "pagination": {
    },
  • "sort": {
    },
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Enrollment

The API facilitates rapid merchant onboarding by enabling batch creation of import MIDs.

Enroll MID batch

The method allows enrolling a batch of MIDs, streamlining the process of registering multiple merchants or card acceptor IDs.

header Parameters
signature
string <= 500 characters

Signature of the request allows verifying whether the request is genuine.

public_key
string <= 500 characters

Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json
Array
description
string

Internal ID or something else that is used to identify the MID.

descriptor
required
string

Payment descriptor.

card_acceptor_id
string

Identification value used by card brands and banks to identify the location of the card acceptor terminal.

acquirer_bin
string

This field contains a six-digit Bank Identification Number (BIN) issued by the merchant's bank or processor.

psp_name
required
string

PSP identifier for recognition.

mcc
string

Setting merchant category codes.

required_products
Array of strings

This parameter specifies the products that enrolled for this CAID.

arns
Array of strings [ 3 .. 10 ] items [ items = 23 characters .{1}4.{21} ]

The Acquirer Reference Number (ARN) is a unique number assigned to a credit card transaction as it moves through the payment flow. It is crucial for tracking transactions, particularly in cases of disputes, refunds, or chargebacks.

merchant_internal_id
string

Internal ID or something else that is used to identify the MID.

Responses

Request samples

Content type
application/json
Example
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "error": {
    }
}

Get enrollment list

The request facilitates the retrieval of enrollment lists through flexible filtering, sorting, and pagination options. Users have the ability to paginate results and apply filters based on parameters such as statuses and descriptions.

The response contains `card_id` that associated with entity from `/api/v2/caids/list`.

header Parameters
signature
string <= 500 characters

Signature of the request allows verifying whether the request is genuine.

public_key
string <= 500 characters

Unique identification that is shared at the moment of registration along with the Private Key.

Request Body schema: application/json
object

Pagination to limit the number of results to help keep network traffic in check.

object

The set of parameters used for detailed filtering.

Responses

Response Schema: application/json
Array of objects

The set of parameters used for detailed information about enrollment lists.

object

Pagination to limit the number of results to help keep network traffic in check.

Request samples

Content type
application/json
{
  • "pagination": {
    },
  • "filter": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Changelog

The changelog is crucial for documenting all modifications, enhancements, and removals to the API. It is essential for developers and users to track changes, understand new features, and adjust their implementations.

Equally important is staying informed about updates in the broader Business Guide changelog, which provides comprehensive details on product-level changes specific to chargeback prevention.


28 February 2024

Removed a deprecated billing_address field from the webhook inquiry response


14 February 2024

Added an outcome field to indicate the outcome of an alert in the responses for the get alert and get alert list endpoints


08 February 2024

Added an info object to indicate the enrollment status of a MID in the responses for the get caid and get caid list endpoints


31 January 2024

Added:

  • made the request body for batch mid enrollment flexible for required field based on the selected required_products
  • implemented the ability to filter by updated_at_from and updated_at_to parameters for the get caid list request