CloudPayments через API и MCP: 32 метода, конверт отказа, который не отличает 400 от отклонённой карты, и Public ID, который просят дважды

Обзор

Как и с ЮKassa: это не про то, чем сама Mira принимает вашу оплату подписки — свой биллинг у неё есть и живёт отдельно. Это про ВАШ магазин. Если вы принимаете платежи через CloudPayments, у вас есть личный кабинет со своей парой Public ID и API Secret, и именно этими ключами агент читает и меняет данные ВАШЕЙ кассы — платежи, выплаты, подписки, счета, претензии.

У CloudPayments, в отличие от ЮKassa, нет официальной машиночитаемой спецификации (OpenAPI/Swagger) — только страница документации и неофициальные клиентские библиотеки на GitHub. Пришлось сверять построчно: выгрузить HTML документации в текст и разобрать каждый из 32 разделов «Адрес метода» вручную, а не угадать по названию. Урок команды, который вспоминают на каждом таком коннекторе: у другого банка 12 денежных действий однажды собрали «по смыслу названий», и все получили бы отказ 400 — ревью на выборке этого не заметило.

Mira подключает этот API целиком — 32 действия в восьми разделах — и отдаёт его в Claude через MCP.

Что доступно

Списание по токену — расход, обычное списание — нет

Барьер записи в Mira делит пишущие действия на «просто меняет» и «ещё и тратит деньги». Первое впечатление: любое списание тратит деньги. На деле — наоборот: обычная оплата картой (charge) деньги магазина не тратит — они, наоборот, ПРИХОДЯТ от покупателя, который сам вводит данные карты и жмёт «оплатить». Расход — это только возврат и три вида выплат, где деньги уходят СО счёта магазина.

Особый случай — списание по сохранённой карте без держателя рядом (token_charge, тот же принцип, что у рекуррентных подписок). Деньги тоже приходят магазину, но карту списывают БЕЗ участия человека в этот момент — магазин действует над чужими деньгами без подтверждения держателя здесь и сейчас. Поэтому это действие помечено тратящим наравне с возвратом и выплатой, хотя по направлению денег оно ближе к обычному платежу.

Success: false — это и «плохой запрос», и «карта отклонена»

Документация сама предупреждает: «поле Success не отражает статус транзакции, а лишь свидетельствует об успешности запроса API». На практике это не спасает — пример отклика на ОТКЛОНЁННУЮ картой транзакцию показывает тот же Success: false, что и пример на некорректно сформированный запрос. Разбор ошибки берёт текст из Message, а для карточных операций донабирает Model.CardHolderMessage — человеческую фразу для держателя карты, которой в Message может не быть вовсе.

Public ID просят дважды

Три платёжные ссылки (СБП, T-Pay, SberPay) авторизуются обычным HTTP Basic — и всё равно требуют идентификатор терминала ПОВТОРНО, полем в теле запроса. Разные способы оплаты называют это поле по-разному: PublicId у СБП и SberPay, но publicId со строчной буквы у T-Pay — отправить капитализацию одного вместо другого значит получить отказ на ровном месте. Агент про это поле знать не должен — Mira подставляет его из собственных настроек источника сама.

Отдельно — у SberPay в документации написано прямо: «HTTP Basic Auth для данного метода не требуется, вместо неё используется PublicId в теле». Mira всё равно шлёт обычный Basic — это не мешает и не требует особого случая в коде ради одного метода из тридцати двух.

Чек — не действие, а поле

У ЮKassa есть отдельное действие «создать чек». У CloudPayments — нет. Фискальный чек (54-ФЗ) собирается ВНУТРИ платежа: полем JsonData = {"cloudpayments": {"CustomerReceipt": {...}}} у обычных платежей, но полем CustomerReceipt на ВЕРХНЕМ УРОВНЕ тела у подписок — то же самое поле по смыслу, две разные формы вложенности в зависимости от метода. Разница задокументирована в таблице вызовов инструмента ровно потому, что перепутать её — тихий отказ без объяснения, а не ошибка формата.

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

Ключей для боевой пары Public ID/API Secret нет — раздел появится, когда владелец магазина их даст. Разбор адреса и тела, барьер записи, HTTP Basic и подстановка Public ID в тело проверены против собственного HTTP-сервера в тестах (перехват на транспорте — тот же приём, что у ЮKassa, Авито и Ozon Performance), а не против api.cloudpayments.ru.