# Prodamus: Принять оплату во встроенном виджете

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

Используй, когда покупатель должен остаться на сайте. Клиентский статус можно показать через `postMessage`, но окончательное подтверждение всё равно приходит по webhook.

1. Подключи `https://widget.prodamus.ru/src/init.js` и `https://widget.prodamus.ru/src/init.css` в `<head>`.
2. Назначь кнопке уникальный ID.
3. Вызови `payformInit` с доменом без `https://` и передай `order_sum` либо `products`.
4. Обработай `window.addEventListener("message")` для статусов `close`, `waiting`, `error`, `success`.
5. Прими `POST {urlNotification}` и подтверди оплату на сервере.

```html
<script defer src="https://widget.prodamus.ru/src/init.js"></script>
<link rel="stylesheet" href="https://widget.prodamus.ru/src/init.css">

<script>
  // если у вас несколько кнопок, то для каждой из кнопок нужно продублировать код ниже, со своим уникальным идентификатором кнопки.
  // UNIQ_IDButton -  техническое название кнопки (должно быть уникальным)
  // UNIQ_ID - уникальный идентификатор кнопки, который
  const UNIQ_IDButton = document.querySelector("#UNIQ_ID")
  // например, если у Вашей кнопки UNIQ_ID это englishCourse, то вместо UNIQ_IDButton следует написать englishCourseButton
  // UNIQ_IDButton - название вашей кнопки
  UNIQ_IDButton?.addEventListener("click", () => {
      payformInit("XXX.payform.ru", { // где, XXX.payform.ru - ссылка на вашу пейформу, без указания https://
          order_sum: 100, // Стоимость заказа в валюте заказа
          currency: "rub", // Валюта заказа. Не обязательный параметр (можно просто удалить всю строчку)
      })
  })
</script>
```

## Базовые URL

- Платёжная страница и REST API: `https://<subdomain>.payform.ru`
- Скрипт виджета: `https://widget.prodamus.ru/src/init.js`
- Стили виджета: `https://widget.prodamus.ru/src/init.css`
- Отдельного тестового URL в изученных страницах не указано: `demo_mode=1`

## Авторизация

Тип: Другое

Секретный ключ доступен в настройках платёжной страницы в блоке «Секретный ключ». Для создания платёжных ссылок, управления подписками и вызова `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 |

### payformInit — Открыть платёжный виджет

Первый аргумент — домен платёжной страницы без `https://`; второй — параметры заказа. Передаётся `order_sum` либо `products`.

Документация: https://help.prodamus.ru/payform/tekhnicheskaya-dokumentaciya/integraciya-platezhnogo-vidzheta#пример-вызова-виджета

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `xxx.payform.ru` | body | string | да | Домен платёжной страницы без https:// |
| `order_sum` | body | number | нет | Обязателен, если нет products |
| `products` | body | array | нет | Обязателен, если нет order_sum |
| `products[i].name` | body | string | да | Наименование товара |
| `products[i].price` | body | number | да | Цена за единицу |
| `products[i].quantity` | body | integer | да | Количество |
| `products[i].sku` | body | string | нет | ID товара в вашей системе |
| `sys` | body | string | нет | Код интеграции от поддержки |
| `urlNotification` | body | string | нет | URL webhook; учитывается вместе с sys |

## Нюансы

- `urlSuccess` и клиентские редиректы не подтверждают поступление денег. Выдавай товар или доступ только после проверенного webhook с `payment_status=success`.
- Подпись запроса считается без поля `signature`; значения приводятся к строкам, ключи сортируются рекурсивно, JSON подписывается HMAC SHA-256 после экранирования `/`.
- Документация webhook называет базовым форматом `application/x-www-form-urlencoded`, а тестовый чек-лист ожидает `multipart/form-data`; для `callbackType=json` приходит `application/json`. Приёмник должен разбирать фактически выбранный формат до проверки `Sign`.
- Повторная доставка webhook допустима: поле `attempt` может увеличиваться. Обработчик должен быть идемпотентным и отвечать `HTTP 200` только после успешной обработки.
- При `subscription` корзина `products` игнорируется. После деактивации подписки от лица пользователя повторная активация невозможна; нужно оформить подписку заново.
- Оплата по связке не поддерживает тестовый режим. Для первого платежа нужен ключ страницы, для `/rest/payment/do/` — отдельный ключ от поддержки, привязанный к `sys`.
- Синхронный `{"success":true}` от `/rest/payment/do/` подтверждает только инициацию. Итог проверяется по webhook с `payment_init=api`.
- Для `GET /rest/payment-methods/getList` `Timestamp` может быть любой непустой строкой: сервер не проверяет формат или актуальность, срок запроса не ограничен и защиты от повторного воспроизведения нет.
- Тело ответа платёжной формы всегда в UTF-8, но `Content-Type` объявляет `charset=WINDOWS-1251`; это отдельно отмечено в примерах C#.
- Статусы `postMessage` гарантированно доступны для карт РФ, СБП и Сбербанк-онлайн. Для других способов оплаты используй webhook.
- Если `available_payment_methods` отфильтровал все способы, параметр игнорируется и показывается полный список; если пустой результат дал `available_payment_method_groups`, форма показывает ошибку об отсутствии методов.
- В демо-платежах защитное изменение подписи применяется только когда боевой режим формы отключил менеджер Prodamus; пользовательский демо-режим в настройках страницы на подпись не влияет.

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

- [Принять разовую оплату по ссылке](https://mcp-everything.ru/integrations/prodamus/scenarios/prinyat-razovuyu-oplatu-po-ssylke.md)
- [Надёжно обработать webhook об оплате](https://mcp-everything.ru/integrations/prodamus/scenarios/nadezhno-obrabotat-webhook-ob-oplate.md)
- [Создать и остановить подписку](https://mcp-everything.ru/integrations/prodamus/scenarios/sozdat-i-ostanovit-podpisku.md)
- [Списать деньги по сохранённой карте](https://mcp-everything.ru/integrations/prodamus/scenarios/spisat-dengi-po-sohranennoy-karte.md)
- [Получить фискальные чеки заказа](https://mcp-everything.ru/integrations/prodamus/scenarios/poluchit-fiskalnye-cheki-zakaza.md)

---

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