Prodamus API

Отрасль: Платежи и финансы. Актуально на 2026-10-12.

API платёжной страницы Prodamus позволяет создавать ссылки на разовую и рекуррентную оплату, принимать платежи во встроенном виджете, получать серверные уведомления и управлять подписками. REST-методы также дают доступ к способам оплаты, фискальным чекам и списаниям по сохранённой карте.

Охват

Есть:

• Разовая оплата: подписанная платёжная ссылка и переход на форму
• Серверное подтверждение оплаты по webhook с проверкой Sign
• Встраивание платёжного виджета и обработка postMessage
• Создание и управление подпиской
• Списание по сохранённой карте
• Получение ссылок на фискальные чеки
• Получение настроенных для домена способов оплаты

Нет — смотри официальную документацию:

• Передача кодов маркировки: POST /rest/mark/addMarks/
• Проверка секретного ключа: POST /rest/validateSecretKey/
• Полный справочник кодов методов и групп оплаты
• Полный набор тестовых карт и тест-кейсов
• Оформление возвратов

Сценарии

Принять разовую оплату по ссылке

Подходит, когда нужно создать заказ на сервере, отправить покупателя на страницу Prodamus и выдать товар только после подтверждённой оплаты.

1. Возьми секретный ключ в настройках платёжной страницы. Если интеграция создаётся для сервиса, запроси у поддержки sys.
2. Собери заказ и подпиши все поля, кроме signature, алгоритмом HMAC SHA-256.
3. Выполни GET /?do=link с products, signature и, если нужен индивидуальный webhook, с sys и urlNotification.
4. Передай покупателю URL из текстового ответа. Для немедленного перехода передай в том же запросе do=pay; endpoint также принимает POST.
5. Прими POST {urlNotification}, проверь заголовок Sign и считай заказ оплаченным только при payment_status=success.

<?php
require_once __DIR__ . '/Hmac.php';

$linkToForm = 'https://demo.payform.ru/';
$secretKey = '2y2aw4oknnke80bp1a8fniwuuq7tdkwmmuq7vwi4nzbr8z1182ftbn6p8mhw3bhz';

$data = [
  'order_id' => 'TEST-1001',
  'customer_phone' => '+79998887755',
  'customer_email' => 'test@example.com',
  'products' => [
    [
      'name' => 'Обучающие материалы',
      'price' => '2000',
      'quantity' => '1',
    ],
  ],
  'do' => 'link',
  'urlReturn' => 'https://merchant.ru/return',
  'urlSuccess' => 'https://merchant.ru/success',
  'urlNotification' => 'https://merchant.ru/api/prodamus/webhook',
  'sys' => 'your_sys_code',
];

$data['signature'] = Hmac::create($data, $secretKey);
$link = sprintf('%s?%s', $linkToForm, http_build_query($data));
echo $link;

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

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());
}

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

Используй, когда покупатель должен остаться на сайте. Клиентский статус можно показать через 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} и подтверди оплату на сервере.

<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>

Создать и остановить подписку

Подходит для регулярных списаний, которыми управляет Prodamus. Подписку сначала создают в личном кабинете, затем покупатель подтверждает первый платёж.

1. Создай подписку в личном кабинете Prodamus и возьми её ID в разделе «Настройки» → «Подписки».
2. Выполни GET /?do=link с subscription, signature и данными клиента. При переданном subscription поле products игнорируется.
3. Отправь ссылку покупателю и прими POST {urlNotification}; первый платёж имеет payment_init=manual, автоматическое списание — payment_init=auto.
4. Чтобы остановить подписку, выполни POST /rest/setActivity/ с subscription, идентификатором клиента и active_manager=0 либо active_user=0.

const { HmacHelper, flattenForm } = require("./hmac");

const LINK_TO_FORM = "<ссылка_на_страницу_оплаты>";
const SECRET_KEY = "<секретный_ключ>";

const data = {
  do: "link",
  // Идентификатор подписки из раздела «Рекуррент и клубы». Если он передан,
  // products не учитывается: состав и цена берутся из настроек подписки.
  subscription: "12345",
  customer_phone: "+79998887755",
  customer_email: "test@example.com",
  // Дата первого списания в формате ГГГГ-ММ-ДД ЧЧ:ММ.
  subscription_date_start: "2026-08-01 12:00",
  // Демо-период в днях: столько подписка действует до первого списания.
  subscription_demo_period: "7",
  // Максимальное количество автоплатежей.
  subscription_limit_autopayments: "12",
  sys: "your_sys_code",
  urlReturn: "https://merchant.ru/return",
  urlSuccess: "https://merchant.ru/success",
  urlNotification: "https://merchant.ru/api/prodamus/webhook",
};

const params = new URLSearchParams(flattenForm(data));
params.append("signature", HmacHelper.create(data, SECRET_KEY));

const requestUrl = `${LINK_TO_FORM}?${params}`;
console.log(requestUrl);

fetch(requestUrl)
  .then((response) => response.text())
  .then((paymentLink) => console.log(paymentLink));

Списать деньги по сохранённой карте

Это управляемые вашей системой повторные списания, а не подписка Prodamus. Сначала нужна небольшая реальная оплата, после которой webhook вернёт binding_id.

1. Согласуй с поддержкой sys и получи отдельный секретный ключ для оплаты по связке.
2. Выполни GET /?do=link без demo_mode, передав стабильный client_id длиной до 32 символов, sys, customer_email, корзину и подпись ключом платёжной страницы.
3. После успешной первой оплаты прими POST {urlNotification} и сохрани пару client_id + binding_id.
4. Выполни POST /rest/payment/do/ с этой парой, корзиной, sys и подписью отдельным ключом связки. Параметр do не передавай.
5. Ответ {"success":true} означает только успешную инициацию; окончательный результат возьми из webhook с payment_init=api.

const { HmacHelper, flattenForm } = require('./hmac/hmac');

const data = {
  products: [{
    name: 'Доступ к обучающим материалам',
    price: '50',
    quantity: '1',
  }],
  client_id: 'customer-4815',
  binding_id: 'TOKEN_FROM_WEBHOOK',
  customer_email: 'customer@example.com',
  customer_phone: '+79998887755',
  urlNotification: 'https://example.com/prodamus/webhook',
  sys: 'your_system',
};

const body = new URLSearchParams(flattenForm(data));
body.append(
  'signature',
  HmacHelper.create(data, process.env.PRODAMUS_BINDING_SECRET_KEY),
);

const response = await fetch(
  'https://YOUR_DOMAIN.payform.ru/rest/payment/do/',
  {
    method: 'POST',
    headers: { 'content-type': 'application/x-www-form-urlencoded;charset=UTF-8' },
    body,
  },
);
const result = await response.json();
if (!response.ok || result.success !== true) {
  throw new Error(result.error ?? `HTTP ${response.status}`);
}

Получить фискальные чеки заказа

Используй после оплаты, чтобы получить ссылки на чеки прихода, возврата или коррекции у оператора фискальных данных.

1. Возьми секретный ключ платёжной страницы.
2. Рассчитай <token> = base64_encode(<timestamp> . md5(<SECRET_KEY>)).
3. Выполни GET /rest/receipt/getReceipts с order_id, заголовками Timestamp и Authorization: Bearer <token>.
4. Обработай массив чеков; пустой массив означает, что доступных чеков нет.

<?php

$domain = 'example.payform.ru';
$secretKey = 'секретный_ключ_домена';
$timestamp = (string) time();
$token = base64_encode($timestamp . md5($secretKey));

$ch = curl_init("https://{$domain}/rest/receipt/getReceipts?order_id=99990091");
curl_setopt_array($ch, [
    CURLOPT_HTTPGET => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Timestamp: {$timestamp}",
        "Authorization: Bearer {$token}",
        'Accept: application/json',
    ],
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

Базовые 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

POST /rest/setActivity/ — Активировать или деактивировать подписку

Менеджер может активировать и деактивировать подписку; пользователь может только деактивировать её.

Документация: https://help.prodamus.ru/payform/tekhnicheskaya-dokumentaciya/rest-api/api-upravlenie-podpiskami#post-/rest/setactivity/

Параметр	Где	Тип	Обяз.	Описание
signature	body	string	да	Подпись запроса
subscription	body	integer	да	ID подписки в Prodamus
customer_phone	body	string	нет	Идентификатор клиента в формате +79999999999
customer_email	body	string	нет	Идентификатор клиента по email
profile	body	integer	нет	ID профиля клиента
tg_user_id	body	integer	нет	ID клиента Telegram
vk_user_id	body	integer	нет	ID клиента ВКонтакте
active_manager	body	boolean	нет	0 — отписан, 1 — подписан менеджером
active_user	body	boolean	нет	Для пользователя доступно только значение 0

Пример ответа:

success

POST /rest/setSubscriptionDiscount/ — Установить скидку на следующие списания

Устанавливает скидку на ограниченное или неограниченное количество будущих платежей.

Документация: https://help.prodamus.ru/payform/tekhnicheskaya-dokumentaciya/rest-api/api-upravlenie-podpiskami#post-/rest/setsubscriptiondiscount/

Параметр	Где	Тип	Обяз.	Описание
signature	body	string	да	Подпись запроса
subscription	body	integer	да	ID подписки в Prodamus
discount_value	body	number	да	Скидка с точностью до двух знаков после точки
num	body	integer	нет	Число оплат со скидкой; по умолчанию 0, без ограничения
customer_phone	body	string	нет	Один из идентификаторов клиента
customer_email	body	string	нет	Один из идентификаторов клиента

GET /rest/receipt/getReceipts — Получить фискальные чеки

Возвращает ссылки на доступные чеки оплаченного заказа. Служебные чеки, включая чеки маркапа и агентского вознаграждения, не возвращаются.

Документация: https://help.prodamus.ru/payform/tekhnicheskaya-dokumentaciya/rest-api/api-fiskalnyy-cheki#get-/rest/receipt/getreceipts

Параметр	Где	Тип	Обяз.	Описание
Authorization	header	string	да	Bearer
Timestamp	header	string	да	Unix timestamp, использованный в токене
order_id	query	integer	да	Номер заказа в Prodamus
is_demo	query	boolean	нет	Запрос для демо-режима платёжной страницы

Пример ответа:

[
  {
    "name": "Чек прихода",
    "link": "https://lk.platformaofd.ru/web/noauth/cheque?fn=7384440900816510&fp=914366710&i=215624",
    "sum": "1.00"
  }
]

GET /rest/payment-methods/getList — Получить способы оплаты домена

Возвращает все настроенные способы оплаты без фильтрации по активности. Состояние находится в is_active и is_acquiring_active.

Документация: https://help.prodamus.ru/payform/tekhnicheskaya-dokumentaciya/rest-api/api-standartnoe#get-/rest/payment-methods/getlist

Параметр	Где	Тип	Обяз.	Описание
Authorization	header	string	да	Bearer ; префикс чувствителен к регистру
Timestamp	header	string	да	Непустая строка, участвующая в подписи

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

curl --request GET 'https://example.payform.ru/rest/payment-methods/getList' \
  --header 'Timestamp: 1735689600' \
  --header 'Authorization: Bearer TOKEN' \
  --header 'Accept: application/json'

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/

setSubscriptionPaymentDate — Перенести дату следующего платежа

Метод с путём /rest/setSubscriptionPaymentDate/ переносит дату только вперёд относительно уже рассчитанной даты следующего платежа. HTTP-метод в заголовке официальной страницы не указан.

Документация: https://help.prodamus.ru/payform/tekhnicheskaya-dokumentaciya/rest-api/api-upravlenie-podpiskami#/rest/setsubscriptionpaymentdate/

Параметр	Где	Тип	Обяз.	Описание
signature	body	string	да	Подпись запроса
subscription	body	integer	да	ID подписки в Prodamus
date	body	string	да	Дата в формате гггг-мм-дд чч:мм
auth_type	body	string	да	tg_user_id, vk_user_id, profile, customer_phone или customer_email
customer_phone	body	string	нет	Обязателен при auth_type=customer_phone
customer_email	body	string	нет	Обязателен при auth_type=customer_email

POST /rest/payment/do/ — Списать деньги по сохранённой карте

Инициирует платёж по паре client_id + binding_id. Документация допускает GET или POST; здесь указан POST, использованный в официальных примерах. Запрос подписывается отдельным ключом, который поддержка привязала к sys; параметр do не передаётся.

Документация: https://help.prodamus.ru/payform/tekhnicheskaya-dokumentaciya/oplata-po-svyazke-cherez-api#шаг-2.-инициируйте-автоплатёж

Параметр	Где	Тип	Обяз.	Описание
products	body	array	да	Корзина списания
products[i].name	body	string	да	Наименование позиции
products[i].price	body	string	да	Цена позиции
products[i].quantity	body	string	да	Количество
client_id	body	string	да	Стабильный ID покупателя, до 32 символов
binding_id	body	string	да	Токен карты из webhook первого платежа
customer_email	body	string	да	Email покупателя
customer_phone	body	string	нет	Телефон покупателя
urlNotification	body	string	нет	HTTPS URL webhook
sys	body	string	да	Согласованный с поддержкой код интеграции
signature	body	string	да	HMAC SHA-256 подпись отдельным ключом связки

Пример ответа:

{"success":true}

Нюансы

• 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; пользовательский демо-режим в настройках страницы на подпись не влияет.

Ошибки

Код	Описание
400	signature not found in request — подпись метода управления подпиской отсутствует или невалидна
401	Authorization failed — подпись неверна или секретный ключ не настроен
405	Wrong request method — использован неподдерживаемый HTTP-метод

Источники

• Техническая документация
• Создание платёжной ссылки
• Webhook об оплате
• Интеграция платёжного виджета
• Создание ссылки с автоплатежом
• API управления подписками
• Оплата по связке
• API фискальных чеков
• API стандартное
• API маркировки товаров
• Тестирование интеграции

---

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