Working with chargeback callbacks

Overview

When working with the ecommpay payment platform, you can enable and use the functionality of daily callbacks with information about events occurring within the chargeback processchargeback process. It is relevant when ecommpay acts an acquirer and interacts with issuers and card networks representing the merchant's interests (details). You can use these callbacks along with other interfaces that provide information about chargebacks (such as the Data API and Dashboard).

Similar to standard callbacks sent from the ecommpay payment platform, chargeback callbacks are HTTP POST requests that contain data in JSON format for processing by the merchant’s web service. However, keep the following special aspects in mind when working with chargeback callbacks:

  • Data is sent without any form of digital signature.
  • Callbacks are sent daily at 12:00 UTC or at 15:00 UTC. If for any reason delivery cannot be performed at this time, callbacks are sent at 15:00 UTC instead.
  • Callbacks are limited to one URL per merchant project.
  • Callbacks are sent only once. Resending callbacks is not supported even if the callback delivery is not acknowledged with the 200 OK response code or if an error response is returned (for example 400 Bad Request).
  • Callbacks are tied to specific stages within the chargeback process and fall into two types: summary and detailed callbacks (details).
  • Callbacks are triggered only if there is updated data. If no changes are detected, no callback is sent.

Refer to your ecommpay account manager to integrate chargeback callbacks.

Callback types

Summary callbacks

Summary callbacks communicate the number of chargebacks for which chargeback process-specific events were recorded in the platform during the reporting period. These events are categorised as follows:

  • new_chargebacks_summary—initiation of chargebacks
  • new_pre_arbitration_summary—advancement of chargebacks to the Pre-Arbitration stage
  • new_arbitration_summary—advancement of chargebacks to the Arbitration stage

For each of these categories, separate callbacks are generated and contain the following set of parameters:

  • event—a category of reportable events (in accordance with the specified options)
  • event_date—the date the event-related data is sent (formatted as YYYY-MM-DD)
  • project_id—the project identifier corresponding to the relevant events
  • merchant_id—the merchant identifier corresponding to the relevant events
  • chargeback_count—the number of chargebacks corresponding to the relevant events
Figure 1. Example of the new_chargebacks_summary object
{
  "event": "new_chargebacks_summary",
  "event_date": "2025-03-15",
  "project_id": "456",
  "merchant_id": "123",
  "chargeback_count": 5
}

Having recorded the information received in the summary callbacks, you can review the itemised chargeback data via detailed callbacks, requests to the Data API (such as /chargeback/list and /chargeback/get; details), or Dashboard (using the Chargebacks section).

Detailed callbacks

Detailed callbacks contain itemised information about chargebacks for which chargeback process-specific events were recorded in the platform during the reporting period. These events are categorised as follows:

  • new_chargeback_details—initiation of chargebacks
  • new_pre_arbitration_details—advancement of chargebacks to the Pre-Arbitration stage
  • new_arbitration_details—advancement of chargebacks to the Arbitration
  • chargeback_cancelled_by_issuer—withdrawal of the chargeback by the issuer, completion of the chargeback process in favour of the merchant
  • chargeback_lost—completion of the chargeback process in favour of the issuer
  • chargeback_won—completion of the chargeback process in favour of the merchant

For each of these categories, separate callbacks are generated and contain the following set of parameters:

  • event—the category of the reported event (in accordance with the specified options)
  • event_date—the date when the event-related data is sent (in the YYYY-MM-DD format)
  • project_id—the identifier of the project for which the reported event is relevant
  • merchant_id—the merchant identifier for which the reported event is relevant
  • total_chargebacks_count—the number of chargebacks for which the reported event is relevant
  • chargebacks—an array of objects containing detailed information about each chargeback for which the reported event is relevant
Note: The parameters of the objects in the chargebacks array match those of the Chargeback object in the Data API (details) with the exception of two parameter names: chargeback_finalization_date instead of chb_completed_at and chargeback_status instead of status.
Figure 2. Example of the chargeback_won object
{
  "event": "chargeback_won",
  "event_date": "2025-03-13",
  "project_id": "12345",
  "merchant_id": "123",
  "total_chargebacks_count": 1,
  "chargebacks": [
    {
      "chargeback_id": "82256",
      "case_id": "11384",
      "operation_id": "5033683310337533",
      "arn": "1",
      "card_type": "MC",
      "chargeback_status": "WON",
      "reason_code": "13.1",
      "report_date": "2025-03-07",
      "pre_arbitration_report_date": null,
      "arbitration_report_date": "2025-03-10",
      "chargeback_finalization_date": "2025-03-13 00:00:00",
      "respond_by": "2025-03-10 23:59:59",
      "charged_amount": -1,
      "charged_currency": "EUR",
      "credited_amount": 1,
      "credited_currency": "EUR"
    }
  ]
}

Having recorded and reviewed the information received in these callbacks, you can proceed to taking subsequent steps of the chargeback process if necessary.

Setup

To enable chargeback callbacks:

  1. Agree with the ecommpay account manager on adding this feature for specific projects, decide on the callback types you need, and provide the destination URL for the web service. Keep in mind that only one URL can be used per merchant project.
  2. Receive a notification from the ecommpay specialists confirming that the feature is enabled.
  3. If relevant chargeback events have occurred, make sure that you have received the corresponding callbacks.

Use

The procedure of responding to each callback on the web service side consists of the following steps:

  1. Accept and confirm the callback receipt.

    For confirming the receipt of callbacks, synchronous HTTP responses should be sent to the payment platform with the corresponding response codes. If no errors have been detected upon the receipt, the response code should be 200 OK. In other cases, the response code should reflect the error type: for example, HTTP 500 Internal Server Error if the callback has been received at an incorrect URL of the web service.

    Note that resending of callbacks is not supported. Regardless of the response, even if it indicates failure to receive the callback, the information sent in previous callbacks is not included in subsequent ones.

  2. Perform the required actions in accordance with the guidelines for handling chargebacks (details) and the specifics of the web service.

Useful links

The following sections can be useful for handling chargeback callbacks:

  • Chargebacks—a section on handling chargebacks (includes an overview, a description of chargeback process, and answers to frequently asked questions).
  • Using Data API—a section on using the API that allows retrieving operation and balance data (includes an overview, a description of interaction with the interface, and detailed information about each endpoints).