Перейти к содержимому

Глава 2 · API-интеграция

Вебхуки и проверка подписи

Как подключить адрес вебхука, какие бывают события, как проверить подпись MirPay-Signature и как работают повторы.

3 мин чтения

На этой странице
  1. Добавление адреса вебхука
  2. События
  3. Как выглядит запрос
  4. Проверка подписи
  5. Ответ и повторы
  6. Старый callback (v1/v2)

Вебхук — это HTTP-запрос, который MirPay отправляет на ваш сервер при изменении статуса платежа. Используйте вебхуки вместо постоянного опроса списков.

Добавление адреса вебхука

  1. Откройте Разработчики → Вебхуки (в нужном режиме — Test или Live).
  2. Нажмите Добавить адрес.
  3. Укажите Адрес (URL). В боевом режиме только HTTPS; адреса внутренней сети и localhost не принимаются.
  4. Выберите Все события или Выбранные события и нажмите Сохранить.
  5. На странице адреса нажмите Показать секрет подписи, получите секрет whsec_… и сохраните его на сервере.

Не более 10 адресов в каждом режиме. Адресами можно управлять и через API: /api/v3/webhook_endpoints. Боевые события отправляются по всем платежам кассы, включая созданные через v2.

Кнопка Отправить тестовое событие отправляет на ваш сервер событие webhook.test — ответ виден в списке Доставки.

События

Событие Когда
payment.succeeded Платёж успешно прошёл.
payment.failed Платёж не прошёл.
payment.canceled Платёж отменён через API или покупателем.
payment.expired Срок платежа истёк.

В будущем могут появиться новые типы: игнорируйте незнакомые, но всё равно возвращайте 2xx.

Как выглядит запрос

MirPay-Signature: t=<unix>,v1=<hex>
MirPay-Event-Id: evt_...
MirPay-Event-Type: payment.succeeded
MirPay-Delivery-Id: whd_...
Content-Type: application/json

Тело (event):

{
  "id": "evt_...",
  "object": "event",
  "type": "payment.succeeded",
  "livemode": true,
  "created": 1731234567,
  "api_version": "2026-11-11",
  "data": { "object": { "id": "...", "object": "payment", "status": "succeeded", "...": "..." } }
}

Проверка подписи

  1. Разбейте заголовок MirPay-Signature по запятым: t — время, v1 — подпись (их может быть несколько).
  2. Составьте строку t + "." + сырое_тело и вычислите HMAC-SHA256 (hex) с секретом.
  3. Сравните результат с каждым v1 сравнением с постоянным временем.
  4. Отклоняйте запрос, если t отличается от текущего времени больше чем на 300 секунд.

Считайте подпись по сырому телу запроса — если фреймворк перекодирует JSON, подпись не совпадёт.

<?php
$secret = getenv("MIRPAY_WEBHOOK_SECRET"); // whsec_...
$body   = file_get_contents("php://input");
$header = $_SERVER["HTTP_MIRPAY_SIGNATURE"] ?? "";

$t = 0; $sigs = [];
foreach (explode(",", $header) as $pair) {
    [$k, $v] = array_pad(explode("=", trim($pair), 2), 2, "");
    if ($k === "t")  $t = (int) $v;
    if ($k === "v1") $sigs[] = $v;
}

$expected = hash_hmac("sha256", $t . "." . $body, $secret);
$valid = $t > 0 && abs(time() - $t) <= 300;
$valid = $valid && array_filter($sigs, fn ($s) => hash_equals($expected, $s));

if (!$valid) { http_response_code(400); exit; }

$event = json_decode($body, true);
if ($event["type"] === "payment.succeeded") {
    $payment = $event["data"]["object"];
    // $payment["id"], $payment["order_id"], $payment["amount"]
}
http_response_code(200);

Ответ и повторы

  • Ответьте любым кодом 2xx в течение 10 секунд. Редиректы (3xx) не выполняются и считаются ошибкой. Тяжёлую работу делайте после ответа.
  • Если 2xx не получен, доставка повторяется: сразу, затем через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч, 12 ч, 24 ч — всего 8 попыток (около 3 дней). После этого доставка помечается failed.
  • Одно и то же событие может прийти несколько раз — сохраняйте MirPay-Event-Id и пропускайте дубли.
  • Порядок событий не гарантируется; перед важным действием перезапросите объект через GET.
  • Пропущенные события можно получить через GET /api/v3/events (хранятся 30 дней).

Автоотключение: если на адрес 72 часа не было ни одной успешной доставки, он переходит в статус Отключено и перестаёт получать события. Исправив проблему, нажмите Включить снова на странице адреса. Недоставленное событие можно отправить вручную кнопкой Отправить повторно.

Если секрет утёк — Заменить секрет (старый перестаёт работать сразу).

Старый callback (v1/v2)

Callback v1/v2 работает без изменений и отправляется в дополнение к вебхукам v3. Он приходит POST-запросом application/x-www-form-urlencoded на URL вебхука из настроек кассы и подписывается секретным ключом callback (раздел Виртуальная касса → Подробнее → Ключи):

X-MirPay-Kassa-Id: <kassa ID>
X-MirPay-Timestamp: <unix>
X-MirPay-Signature: <hex>

signature = HMAC_SHA256(timestamp + "." + raw_body, callback_secret)

При неудаче callback повторяется до 5 раз — ваш обработчик не должен выполнять заказ дважды, если один и тот же payid пришёл повторно.

Статья была полезной?

Не нашли ответ?

Отправьте обращение — специалист проверит ваш аккаунт и ответит.