Оповещения H2H

В этом разделе описаны оповещения (колбеки) при интеграции по API (H2H). Оповещения используются для уведомления мерчанта об изменении статуса заявки: промежуточные статусы, успешное завершение и ошибки.

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

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

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

При работе по схеме H2H:

  • бэкенд мерчанта создает заявку через API (например, P2P или ECOM);

  • в ответе API мерчант получает первичный статус (status, sub_status);

  • при дальнейшем изменении статуса HighHelp отправляет HTTP-запрос на заранее заданные URL.

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

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

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

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

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

При H2H-интеграции используются три типа оповещений:

  • Информативные оповещения — отправляются при каждом изменении промежуточного статуса заявки, когда значение status остается processing, а sub_status меняется (например, переход в состояния проверки реквизитов или ожидания 3-D Secure). Используются для онлайн-отображения хода обработки и для журналирования, но не должны запускать финальные бизнес-действия по заказу (отгрузка, выдача услуги и т.п.).

  • Успешные оповещения — отправляются один раз при переходе заявки в финальное состояние success. Содержат итоговые параметры операции (сумма, валюта, метод, идентификаторы) и подтверждают, что платеж или выплата завершены успешно и не требуют дополнительных попыток обработки на стороне платежного шлюза. Используются для фиксации оплаты или выполнения выплаты в системе мерчанта и последующих бизнес-действий (подтверждение заказа, изменение баланса и т.п.).

  • Неуспешные оповещения — отправляются при завершении заявки в финальном неуспешном состоянии (decline или error, включая случаи истечения времени жизни заявки). Содержат текущее значение status, sub_status и status_description, по которым можно определить причину отказа или ошибки. Используются для фиксации того, что операция не выполнена, освобождения зарезервированных ресурсов и предложения пользователю повторить платеж или оформить новую заявку.

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

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

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

Примеры статусов:

  • processing:new;

  • processing:awaiting_3ds_result;

  • processing:awaiting_redirect_result;

  • processing:payout_process;

  • другие промежуточные статусы из Коды статусов.

URL для информативных оповещений задается в параметре merchant_callback_url при создании заявки.

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

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

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

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "ECOM-H2H-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-H2H-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.

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

  • Метод: POST.

  • Заголовки:

  • Тело: JSON-объект с полями заявки и статуса.

Ниже приведен пример успешного оповещения по операции payin (структура может отличаться в зависимости от продукта и метода):

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

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

  • project_id — идентификатор кассы (проекта) мерчанта.

  • general — блок с идентификаторами заявки.

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

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

  • status — блок со статусом обработки.

    • status — основной статус (например, processing, success, decline, error).

    • sub_status — подстатус (может быть null для некоторых состояний).

    • status_description — дополнительное текстовое описание статуса (обычно заполняется при ошибках и отказах).

  • payment_info — блок с параметрами платежа.

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

    • currency — код валюты в формате ISO 4217 alpha-3.

    • method — метод оплаты или выплаты.

    • type — тип платежа (payin или payout).

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

Оповещения с данными для аутентификации

Для некоторых операций ECOM H2H (например, при 3-D Secure) оповещение может содержать дополнительные данные для аутентификации клиента у эмитента.

Пример для статуса processing:awaiting_3ds_result:

{
  "project_id": "57aff4db-b45d-42bf-bc5f-b7a499a01782",
  "general": {
    "request_id": "16a10539-fcb3-4ff5-a3e2-86625a2dc3d3",
    "payment_id": "KZT-ECOM-123456"
  },
  "status": {
    "status": "processing",
    "sub_status": "awaiting_3ds_result",
    "status_description": null
  },
  "payment_info": {
    "amount": 7000,
    "currency": "KZT",
    "method": "card-ecom",
    "type": "payin"
  },
  "asc_info": {
    "pa_req": "123456789",
    "acs_url": "https://acs-url.com/order/1234",
    "md": "V2hhdCdzIHVwIGR1ZGU="
  }
}

Блок asc_info содержит данные для формирования формы аутентификации через 3-D Secure. Подробный пример обработки 3-D Secure приведен в разделе Одностадийная оплата.

Аналогично, при использовании сценариев с редиректом может использоваться блок redirect_info с параметрами:

  • method — HTTP-метод для запроса.

  • url — адрес для перенаправления клиента.

  • body — параметры запроса (может быть пустым).

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

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

  • получить актуальный публичный ключ в кабинете мерчанта (публичный ключ привязан к конкретной кассе);

  • использовать алгоритм проверки, описанный в разделе Аутентификация и подпись.

Рекомендации:

  • проверять подпись всех входящих оповещений перед обработкой;

  • при ошибке проверки подписи фиксировать инцидент и не выполнять бизнес-логику по такому оповещению;

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

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

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

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

  • 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 (например, p2p/payin/info, ecom/payin/info, ecom/payout/info). Форматы запросов и ответов описаны в профильных разделах, таких как Одностадийная оплата и руководства по P2P для соответствующих стран.