Работа с программными оповещениями об опротестованиях платежей

Общая информация

При работе с платёжной платформой можно подключить и использовать ежедневные программные оповещения о событиях, связанных с оформлением и рассмотрением опротестований финансовых операцийопротестований финансовых операций. Это актуально в тех случаях, когда ecommpay выступает как эквайер и взаимодействует со стороны мерчанта с эмитентами и платёжными системами (подробнее), и может быть полезным наряду с использованием других интерфейсов, позволяющих получать информацию об опротестованиях (таких, как Data API и Dashboard).

Оповещения об опротестованиях, как и основные оповещения от платёжной платформы, технически представляют собой HTTP-POST-запросы с вложенной в них информацией в формате JSON для приёма и обработки на стороне веб-сервиса мерчанта. При этом в работе с оповещениями об опротестованиях есть ряд особенностей:

Передаваемые данные не подкрепляются цифровыми подписями.
Оповещения отправляются раз в сутки: в 12:00 UTC либо, если по каким-либо причинам отправка не может быть выполнена в это время, в 15:00 UTC.
Оповещения отправляются не больше чем на один URL для одного проекта мерчанта.
Оповещения отправляются однократно. Повторная отправка не применяется, даже если получение какого-либо оповещения не было подтверждено ответным сообщением (с кодом ответа 200 ОК) или если был передан ответ с ошибкой (например, с кодом ответа 400 Bad Request).
Оповещения профилируются по стадиям работы с опротестованиями и делятся на два вида: со сводной и детализированной информацией (подробнее далее).
Оповещения отправляются только при наличии новой профильной информации (относительно предыдущей отправленной). Если профильных обновлений нет, оповещения об этом не отправляются.

Подключение программных оповещений об опротестованиях финансовых операций осуществляется по согласованию с курирующим менеджером ecommpay.

Виды оповещений

Оповещения со сводной информацией

Сводные оповещения содержат информацию о количестве опротестований, по которым за отчётное время в платформе были зарегистрированы профильные события. Эти события делятся на следующие категории:

new_chargebacks_summary — оформление опротестований финансовых операций;
new_pre_arbitration_summary — перевод опротестований на этап Pre-Arbitration („Преарбитраж“);
new_arbitration_summary — перевод опротестований на этап Arbitration („Арбитраж“).

По каждой из этих категорий формируются отдельные оповещения, включающие в себя следующий набор параметров:

event — категория отчётных событий (в соответствии с указанными вариантами);
event_date — дата отправки информации об отчётных событиях, в формате YYYY-MM-DD;
project_id — идентификатор проекта, к которому относятся отчётные события;
merchant_id — идентификатор мерчанта, к которому относятся отчётные события;
chargeback_count — количество опротестований, к которым относятся отчётные события.

Рис. 1. Пример объекта new_chargebacks_summary

{
  "event": "new_chargebacks_summary",
  "event_date": "2025-03-15",
  "project_id": "456",
  "merchant_id": "123",
  "chargeback_count": 5
}

При получении таких оповещений можно фиксировать полученную информацию и знакомиться с детальными сведениями через детализированные оповещения, через запросы к Data API (такие, как /chargeback/list и /chargeback/get; подробнее) или через раздел Чарджбэки интерфейса Dashboard.

Оповещения с детализированной информацией

Детализированные оповещения содержат информацию об опротестованиях, по которым за отчётное время в платформе были зарегистрированы профильные события. Эти события делятся на следующие категории:

new_chargeback_details — оформление опротестований финансовых операций;
new_pre_arbitration_details — перевод опротестований на этап Pre-Arbitration („Преарбитраж“);
new_arbitration_details — перевод опротестований на этап Arbitration („Арбитраж“);
chargeback_cancelled_by_issuer — отзыв опротестований эмитентом, с завершением рассмотрений в пользу мерчанта;
chargeback_lost — завершение работы с опротестованиями в пользу эмитента;
chargeback_won — завершение работы с опротестованиями в пользу мерчанта.

По каждой из этих категорий формируются отдельные оповещения, включающие в себя следующий набор параметров:

event — категория отчётных событий (в соответствии с указанными вариантами);
event_date — дата отправки информации об отчётных событиях, в формате YYYY-MM-DD;
project_id — идентификатор проекта, к которому относятся отчётные события;
merchant_id — идентификатор мерчанта, к которому относятся отчётные события;
total_chargebacks_count — количество опротестований, к которым относятся отчётные события;
chargebacks — массив объектов с информацией о каждом из опротестований, к которому относятся отчётные события.

Прим.: Параметры объектов массива chargebacks соответствуют параметрам объекта Chargeback Data API (подробнее) с разницей в названиях двух параметров: chargeback_finalization_date вместо chb_completed_at и chargeback_status вместо status.

Рис. 2. Пример объекта chargeback_won

{
  "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"
    }
  ]
}

При получении таких оповещений можно фиксировать полученную информацию и, когда это актуально, выполнять необходимые действия по работе с конкретными опротестованиями.

Подключение

Чтобы подключить программные оповещения об опротестованиях финансовых операций, со стороны мерчанта следует:

Согласовать с курирующим менеджером ecommpay подключение этой возможности для конкретных проектов, актуальные виды оповещений и адрес для приёма данных на стороне веб-сервиса (следует учитывать, что может использоваться лишь один URL на один проект мерчанта).
Получить от специалистов ecommpay уведомление о подключении запрошенной функциональности.
По возможности (при наличии целевых событий по опротестованиям) проверить получение согласованной информации.

Использование

Порядок реагирования на каждое поступающее оповещение об опротестованиях со стороны веб-сервиса сводится к следующим шагам:

Принять оповещение и подтвердить его получение.
Чтобы подтверждать получение оповещений, необходимо отправлять к платёжной платформе синхронные HTTP-сообщения: при приёме оповещений без ошибок — с кодом ответа 200 ОК, в остальных случаях — с кодами ответов, соответствующими ошибкам, например HTTP 500 Internal Server Error, если оповещение поступило на некорректный URL веб-сервиса.
Следует учитывать, что повторная отправка оповещений не предусмотрена и независимо от ответа, даже если он содержит информацию об ошибке, в следующую рассылку отправленная ранее информация не включается.
Выполнить необходимые действия в соответствии с порядком работы с опротестованиями (подробнее) и спецификой работы веб-сервиса.

Дополнительные материалы

При работе с программными оповещениями об опротестованиях финансовых операций могут быть полезны следующие материалы:

Работа с опротестованиями — раздел о работе с опротестованиями финансовых операций, включая общую информацию, описание порядка работы и ответы на различные вопросы;
Использование Data API — раздел о работе с программным интерфейсом получения информации о платежах и балансах, включая общую информацию, описание порядка работы и сведения о работе с каждой из конечных точек.