Оповещения виджета

В этом разделе описаны HTTP-оповещения (колбеки), которые HighHelp отправляет при изменении статуса заявок, созданных через платежный виджет (H2C). Обзор работы виджета приведен в разделе Обзор виджета.

Определения статусов и подстатусов приведены в разделе Коды статусов. Механизм аутентификации и подписи описан в разделе Аутентификация и подпись.

Назначение оповещений

Оповещения виджета используются для передачи результата обработки заявки с платформы HighHelp на бэкенд мерчанта.

Оповещения нужны для:

  • отслеживания прогресса обработки заявки;

  • фиксации финального результата (успех или ошибка);

  • получения дополнительных данных (сумма, валюта, маскированные реквизиты, данные для аутентификации и др.).

Структура оповещений для заявок, созданных через виджет, совпадает со структурой оповещений для заявок, созданных по API (H2H). Описание общих статусов и подстатусов приведено в разделе Коды статусов.

Типы оповещений

Для заявок, созданных через виджет, используются три типа оповещений:

  • Информативные оповещения — отправляются при переходе заявки в промежуточные статусы.URL для информативных оповещений указывается в поле merchant_callback_url при создании заявки.

  • Успешные оповещения — отправляются при переводе заявки в финальный статус success. URL указывается в поле merchant_success_callback_url.

  • Неуспешные оповещения — отправляются при переводе заявки в финальный статус decline или error. URL указывается в поле merchant_decline_callback_url.

Статусы, подстатусы и их значения описаны в разделе Коды статусов.

Транспорт и формат

HighHelp отправляет оповещения:

  • методом POST;

  • в формате JSON;

  • с кодировкой UTF-8;

  • с заголовком Content-Type: application/json.

Каждое оповещение содержит:

  • данные о кассе и платеже;

  • текущий статус и подстатус;

  • информацию о сумме, валюте и методе;

  • дополнительные блоки, специфичные для продукта, например, информация о карте или клиенте.

Примеры структур JSON приведены ниже.

Информативные оповещения

Информативные оповещения отправляются при переходе заявки в промежуточные статусы. Пример информативного оповещения для интернет-платежа через виджет:

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "ECOM-WIDGET-0001"
  },
  "status": {
    "status": "processing",
    "sub_status": "awaiting_redirect_result",
    "status_description": null
  },
  "payment_info": {
    "amount": 10000,
    "currency": "RUB",
    "lifetime": 300,
    "expiration_date": 1721647251,
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payin"
  }
}

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

Успешные оповещения

Успешные оповещения отправляются, когда заявка переходит в финальный статус success. URL для успешных оповещений задается в параметре merchant_success_callback_url.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "ECOM-WIDGET-0001"
  },
  "status": {
    "status": "success",
    "sub_status": null,
    "status_description": null
  },
  "payment_info": {
    "amount": 10000,
    "currency": "RUB",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payin"
  }
}

Такие оповещения используются для:

  • фиксации успешного списания или выплаты;

  • выполнения бизнес-логики мерчанта (изменение статуса заказа, выдача услуги, зачисление бонусов и т.п.).

При получении такого оповещения рекомендуется:

  • зафиксировать успешное завершение операции в системе мерчанта;

  • обновить состояние заказа;

  • не выполнять повторное списание или повторную обработку по уже обработанной заявке.

Неуспешные оповещения

Неуспешные оповещения отправляются, когда заявка переходит в финальный статус decline или error. URL для неуспешных оповещений задается в параметре merchant_decline_callback_url.

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "ECOM-WIDGET-0001"
  },
  "status": {
    "status": "decline",
    "sub_status": null,
    "status_description": "Declined by anti-fraud"
  },
  "payment_info": {
    "amount": 10000,
    "currency": "RUB",
    "updated_date": 1721647251,
    "created_date": 1721647251,
    "method": "card-ecom",
    "type": "payin"
  }
}

Причины отказа описываются в полях status и status_description. Коды и значения статусов приведены в разделе Коды статусов.

Формат оповещения

оповещение представляет собой HTTP POST-запрос в формате JSON.

Общие параметры:

Общая структура оповещения:

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "ECOM-WIDGET-0001"
  },
  "status": {
    "status": "processing",
    "sub_status": "new",
    "status_description": null
  },
  "payment_info": {
    "amount": 10000,
    "currency": "RUB",
    "method": "card-ecom",
    "type": "payin"
  },
  "customer": {
    "id": "cus_12345"
  }
}

Основные поля:

  • project_id — идентификатор кассы в системе HighHelp.

  • general — общая информация о заявке.

    • request_id — идентификатор заявки в системе HighHelp.

    • payment_id — идентификатор платежа в системе мерчанта.

  • status — статус обработки заявки.

    • status — основной статус заявки. Значения описаны в Коды статусов.

    • sub_status — подстатус заявки. Значения описаны в Коды статусов.

    • status_description — текстовое описание статуса, используется в случае ошибок или отказов.

  • payment_info — параметры платежа.

    • amount — сумма в дробных единицах валюты.

    • currency — код валюты в формате ISO 4217 alpha-3. Варианты описаны в Коды валют.

    • method — базовый метод обработки платежа (например, card-ecom). Значения описаны в Методы оплаты (H2H).

    • widget_method — (если присутствует) метод платежной страницы. Значения описаны в Методы виджета.

    • type — тип платежа (payin или payout). Значения описаны в Типы платежей.

  • customer — информация о клиенте.

    • id — идентификатор клиента в системе мерчанта.

Конкретный состав полей может отличаться в зависимости от продукта и метода (P2P, ECOM, выплата).

Полный перечень возможных статусов и подстатусов приведен в Коды статусов.

Данные для аутентификации (3-D Secure)

Для заявок, созданных через платежный виджет данные для прохождения 3-D Secure и других видов аутентификации обрабатываются внутри виджета HighHelp. В HTTP-оповещениях на бэкенд мерчанта не передаются блоки asc_info и redirect_info, описанные для H2H-интеграции.

Бэкенд мерчанта получает только статус операции (status, sub_status, status_description) и платежные атрибуты. Подробный пример работы 3-D Secure в H2H-сценарии приведен в разделе Одностадийная оплата.

Проверка подписи оповещений

Каждое оповещение подписывается цифровой подписью на стороне HighHelp. Поддерживаются два алгоритма подписи:

  • RSA-SHA256;

  • HMAC-SHA512.

Для проверки подписи выполните шаги:

  1. Получите ключ для проверки подписи в личном кабинете мерчанта:

    1. Откройте раздел API → Настройки Callback.

    2. В модальном окне найдите блок:

      • Public Key — если для кассы настроен алгоритм RSA;

      • HMAC key — если для кассы настроен алгоритм HMAC.

    3. Нажмите на иконку скачивания и сохраните файл ключа.

  2. Настройте сервис обработки оповещений на использование соответствующего ключа:

    1. для RSA используйте публичный ключ из блока Public Key;

    2. для HMAC используйте секретный HMAC-ключ из блока HMAC key.

  3. Реализуйте алгоритм проверки подписи в соответствии с выбранным алгоритмом подписи:

  • Проверяйте подпись всех входящих оповещений перед обработкой бизнес-логики.

  • При ошибке проверки подписи фиксируйте инцидент и не выполняйте операции по такому оповещению.

  • Не используйте неподтвержденные данные без проверки подписи для проведения операций на стороне мерчанта.

Идемпотентность и обработка дубликатов

Оповещения могут быть отправлены повторно, если:

  • предыдущий запрос завершился с ошибкой;

  • HighHelp не получил успешный HTTP-ответ от сервера мерчанта;

  • сервер мерчанта ответил с кодом, отличным от диапазона 2xx;

  • произошла повторная попытка доставки.

Рекомендуется:

  • реализовать проверку на дубликаты;

  • использовать ключ идемпотентности вида {project_id}:{payment_id}:{status}:{sub_status};

  • игнорировать повторные оповещения с уже обработанным сочетанием status и sub_status.

Это позволяет избежать повторной обработки одной и той же операции при повторной доставке оповещений.

Если оповещение невозможно доставить (ошибка сети или неуспешный ответ сервера мерчанта), система повторяет попытки отправки до тех пор, пока не истечет срок жизни заявки. Поэтому важно, чтобы обработка оповещения была идемпотентной и не требовала длительного времени выполнения.

Ответ мерчанта на оповещение

Рекомендуемый формат ответа на оповещение:

  • HTTP-статус: 200 OK при успешной обработке.

  • Тело ответа: пустое или короткое подтверждение (например, {"status":"ok"}).

На стороне бэкенда мерчанта рекомендуется реализовать следующий алгоритм обработки:

  1. Принять HTTP-запрос POST с телом JSON.

  2. Проверить цифровую подпись оповещения.

  3. Считать ключ идемпотентности {project_id}:{payment_id}:{status}:{sub_status}.

  4. Проверить, обрабатывался ли уже данный ключ.

    • если обрабатывался, вернуть успешный HTTP-ответ и завершить обработку;

    • если не обрабатывался, выполнить бизнес-логику.

  5. В зависимости от значения status:

    • для success зафиксировать успешное завершение;

    • для decline или error зафиксировать отказ или ошибку;

    • для processing:* при необходимости обновить промежуточное состояние.

  6. Записать результат обработки в журнал.

  7. Вернуть HTTP-ответ с кодом 2xx в случае успешной обработки.

Это поведение одинаково для заявок, созданных через виджет и через H2H.

Практические рекомендации

Рекомендуется:

  • логировать все полученные оповещения с ключевыми полями:

    • project_id, payment_id, request_id;

    • status, sub_status, status_description;

    • значения сумм и валют;

  • проверять подпись перед выполнением бизнес-логики;

  • реализовать идемпотентность по ключу {project_id}:{payment_id}:{status}:{sub_status};

  • обрабатывать как финальные (success, decline, error), так и промежуточные статусы;

  • при необходимости получать актуальный статус заявки через методы …​/info для соответствующего продукта (например, метод widget/payin/info для ECOM через виджет или другие инфо-методы, описанные в продуктовых разделах).

Следующие шаги

Для настройки и отладки работы виджета: