Robokassa через API и MCP: три схемы подписи вместо одного токена, и почему GetRates у неё больше не существует

Обзор

Тот же класс задачи, что у ЮKassa: Robokassa — не про то, как Mira принимает вашу оплату подписки, это про ВАШ магазин. У вас свой личный кабинет со своим MerchantLogin и парой (иногда тройкой) паролей, и именно ими агент читает и меняет данные вашей кассы — платёжные ссылки, холдирование, рекуррентные списания, счета, чеки, возвраты.

Отличие от ЮKassa начинается на первой странице документации. У ЮKassa — один HTTP Basic на каждый запрос. У Robokassa — три РАЗНЫЕ схемы подписи одновременно, два разных хоста API, и справочные методы отвечают XML, а не JSON. Собрать это по памяти нельзя — мы разобрали официальную OpenAPI-спецификацию (robokassa.yaml, версия 1.3.0) программно, и в ней обнаружился любопытный факт: методы GetRates и CalcOutSumm, которые всё ещё встречаются в старых инструкциях по интеграции, в текущем контракте отсутствуют вовсе.

Три схемы подписи, не одна

• Контрольная сумма в запросе — хэш строки, собранной по формуле действия, Паролем#1 (у одного метода — Паролем#2). Формула не одна на всё: у отмены холдирования сумма платежа вообще выпадает из строки подписи, оставляя пустой сегмент, — не ошибка, а буквальная формула из спецификации.
• JWT, подписанный Паролем#1 — Invoice API (счета) и регистрация отложенного чека. Секрет — конкатенация MerchantLogin:Пароль#1, заголовок токена называет алгоритм MD5 — нестандартно для JWT, но именно так называет его сама спецификация Robokassa.
• JWT, подписанный Паролем#3 — только возврат, и только он. Пароль#3 не выдаётся по умолчанию: его нужно отдельно включить в личном кабинете, и без этого API возвратов отвечает 401.

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

Один API — два хоста и три формата ответа

auth.robokassa.ru отвечает за платёжные страницы, холдирование, рекуррент и XML-справочники. services.robokassa.ru — за Invoice API, регистрацию чеков и возвраты. Спецификация называет хост у каждой операции отдельно — угадать по пути нельзя.

Форматы ответа тоже не единообразны: JSON — у Invoice API, возвратов, SMS; XML — у статуса операции (OpStateExt) и списка валют (GetCurrencies), с полным пространством имён SOAP-эпохи на каждом теге; голый текст OK{id} — у успешного рекуррентного платежа, и application/problem+json — у его отказа; наконец, у платёжных ссылок код ошибки может прийти внутри HTML-страницы (RoboxContext.error.code=29) под HTTP 200 — статус-код тут ничего не говорит об успехе.

Методов, которых больше нет

Задание на этот коннектор предполагало, что у Robokassa есть GetPaymentMethods, GetRates и CalcOutSumm — эти имена встречаются в старых интеграционных гайдах. Официальная OpenAPI-спецификация, машиночитаемая и датированная 2026-08-10, их не содержит вовсе: из справочных XML-методов остались только OpStateExt (статус операции) и GetCurrencies (доступные валюты и способы оплаты). Мы не стали изобретать по памяти то, чего в текущем контракте нет, — и назвали расхождение явно, а не тихо пропустили.

Возврат — единственное тратящее действие

Как и у ЮKassa, барьер записи в Mira делит пишущие действия на «просто меняет» и «ещё и тратит деньги магазина». Платёжная ссылка, оплата по сохранённой карте, сплит-платёж — под барьером как видимый снаружи артефакт, но деньги при этом ПРИХОДЯТ магазину, не тратятся. Подтверждение и отмена холдирования — то же самое: приход или его остановка. Рекуррентное списание берёт деньги у ПОКУПАТЕЛЯ, а не у магазина. Из 17 действий Robokassa только одно — создание возврата — реально уводит деньги со счёта магазина обратно покупателю.

Живая проверка

Живых MerchantLogin/паролей нет — раздел появится, когда владелец магазина их даст. Формулы подписи (все три схемы), разбор XML, HTML-редиректов и JSON-конвертов проверены против собственного HTTP-сервера в тестах — перехват на транспорте, тот же приём, что у ЮKassa и Авито, — а не против auth.robokassa.ru.