Prodamus: Надёжно обработать webhook об оплате

Сценарий из mcp-everything. Актуально на 2026-10-12.

Webhook — рекомендуемый источник окончательного статуса. Сценарий заканчивается проверенной подписью, идемпотентно обновлённым заказом и ответом HTTP 200.

  1. Подготовь публичный HTTPS endpoint и передай его как urlNotification вместе с sys в GET /?do=link.
  2. Прими POST {urlNotification} и извлеки подпись из заголовка Sign.
  3. Проверь Sign методом Hmac::verify на исходных полях тела и секретном ключе платёжной страницы.
  4. При неверной подписи верни код, отличный от 200, и прекрати обработку.
  5. При payment_status=success выполни бизнес-операцию идемпотентно; после успешной обработки верни HTTP 200.
<?php
require_once __DIR__ . '/Hmac.php';

$secret_key = 'ваш_секретный_ключ';
$headers = apache_request_headers();

try {
    if ( empty($_POST) ) {
        throw new Exception('$_POST is empty');
    }
    elseif ( empty($headers['Sign']) ) {
        throw new Exception('signature not found');
    }
    elseif ( !Hmac::verify($_POST, $secret_key, $headers['Sign']) ) {
        throw new Exception('signature incorrect');
    }

    http_response_code(200);
    echo 'success';
}
catch (Exception $e) {
    http_response_code($e->getCode() ? $e->getCode() : 400);
    printf('error: %s', $e->getMessage());
}

Базовые URL

Авторизация

Тип: Другое

Секретный ключ доступен в настройках платёжной страницы в блоке «Секретный ключ». Для создания платёжных ссылок, управления подписками и вызова GET или POST /rest/payment/do/ данные запроса без поля signature рекурсивно приводят к строкам, сортируют по ключам, преобразуют в JSON, экранируют / и подписывают HMAC SHA-256. Готовые реализации Hmac.php, hmac.js, prodamus_hmac.py, HmacHelper.cs, HmacHelper.java и hmac.go опубликованы на страницах документации.

Входящий webhook подписан в заголовке Sign; подпись проверяется тем же секретным ключом платёжной страницы. Для оплаты по связке поддержка выдаёт отдельный ключ, привязанный к sys; ключ платёжной страницы используют только для первого платежа.

Для GET /rest/receipt/getReceipts и GET /rest/payment-methods/getList передаются заголовки Timestamp и Authorization: Bearer <token>, где <token> = base64_encode(<timestamp> . md5(<SECRET_KEY>)).

Методы сценария

{urlNotification} — Получить webhook об оплате

Prodamus отправляет итоговый статус платежа методом POST. При успешной обработке endpoint должен вернуть HTTP 200.

Документация: https://help.prodamus.ru/payform/tekhnicheskaya-dokumentaciya/webhook-ob-oplate

Параметр Где Тип Обяз. Описание
Sign header string да HMAC-подпись входящего тела
date body string да Дата платежа
order_id body number да ID заказа в Prodamus
order_num body string да Номер заказа на стороне магазина; может быть пустым
sum body string да Сумма заказа
currency body string да rub, usd или eur
attempt body string да Номер попытки доставки
products body array да Корзина товаров
products[i].name body string да Наименование товара
products[i].price body number да Цена за единицу
products[i].quantity body integer да Количество
payment_status body string да success, order_canceled или order_denied
payment_status_description body string да Расшифровка статуса
payment_init body string да api, auto или manual

GET /?do=link — Создать платёжную ссылку

Endpoint возвращает ссылку при do=link или сразу открывает форму при do=pay. Запрос также можно отправить методом POST с телом application/x-www-form-urlencoded или multipart/form-data.

Пример ответа при do=link:

Документация: https://help.prodamus.ru/payform/tekhnicheskaya-dokumentaciya/sozdanie-platezhnoy-ssylki#запрос-на-создание-ссылки-/-переход-к-оплате

Параметр Где Тип Обяз. Описание
do query string да link — вернуть ссылку; pay — перейти к оплате
products query array нет Корзина; без неё клиент заполняет товар на странице
products[i].name query string да Наименование переданной позиции
products[i].price query number да Цена за единицу переданной позиции
products[i].quantity query integer да Количество переданной позиции
order_sum query number нет Сумма заказа; при do=link без products становится ценой базового товара
order_id query string нет Номер заказа в вашей системе
customer_phone query string нет Телефон клиента
customer_email query string нет Email клиента
sys query string нет Код интеграции от поддержки; обязателен для интеграции сервиса
urlNotification query string нет URL webhook; учитывается вместе с sys
urlReturn query string нет URL возврата без оплаты
urlSuccess query string нет URL возврата после успешной оплаты
subscription query integer нет ID подписки; если он передан, products игнорируется
demo_mode query integer нет Значение 1 включает демо-режим для платежа
callbackType query string нет Значение json запрашивает webhook в JSON
signature query string да HMAC SHA-256 подпись запроса

Пример запроса:

https://payform.ru/h9brIKu/

Нюансы

Другие сценарии

Если этого недостаточно — официальная документация: https://help.prodamus.ru/payform/tekhnicheskaya-dokumentaciya Вся интеграция одним документом: https://mcp-everything.ru/integrations/prodamus.md