# Working with chargeback callbacks {#en_dbl_chargeback_callbacks}

An article about the capabilities of working with callbacks that communicate information about events occurring within the chargeback process.

**Parent topic:**[Dashboard](en_dbl_about.md)

## Overview {#en_dbl_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 process.It is relevant when Ecommpay acts an acquirerand interacts with issuers and card networksrepresenting the merchant's interests \([details](en_faq_chargebacks.md)\). 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. 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 supportedeven 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](en_dbl_chargeback_callbacks.md#)\).
-   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 {#en_dbl_chargeback_callbacks_types}

### Summary callbacks {#section_yg2_qfq_tgc .section}

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 datethe event-related data is sent\(formatted as `YYYY-MM-DD`\)
-   `project_id`—the project identifiercorresponding to the relevant events
-   `merchant_id`—the merchant identifiercorresponding to the relevant events
-   `chargeback_count`—the number of chargebackscorresponding to the relevant events

``` {#codeblock_pns_p3q_tgc .language-json}
{
  "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](en_dbl_api_protocol.md)\), or Dashboard \(using the **Chargebacks** section\).

### Detailed callbacks {#section_rzs_djq_tgc .section}

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 whenthe event-related data is sent\(in the `YYYY-MM-DD` format\)
-   `project_id`—the identifier of the projectfor which the reported event is relevant
-   `merchant_id`—the merchant identifierfor which the reported event is relevant
-   `total_chargebacks_count`—the number of chargebacksfor which the reported event is relevant
-   `chargebacks`—an array of objects containing detailed information about each chargebackfor 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](https://api-data.ecommpay.com/)\) with the exception of two parameter names: `chargeback_finalization_date` instead of `chb_completed_at` and `chargeback_status` instead of `status`.

``` {#codeblock_i4p_mxn_lgc .language-json}
{
  "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 {#en_dbl_chargeback_callbacks_setup}

To enable chargeback callbacks:

1.  Agree with the Ecommpay account manager on adding this featurefor 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 specialistsconfirming that the feature is enabled.
3.  If relevant chargeback events have occurred, make sure that you have received the corresponding callbacks.

## Use {#en_dbl_chargeback_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](en_faq_chargebacks.md#section_ppz_lhs_q5b)\) and the specifics of the web service.

## Useful links {#en_dbl_chargeback_callbacks_useful_links}

The following sections can be useful for handling chargeback callbacks:

-   [Chargebacks](en_faq_chargebacks.md)—a section on handling chargebacks \(includes an overview, a description of chargeback process, and answers to frequently asked questions\).
-   [Using Data API](en_dbl_api_protocol.md)—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\).