Robokassa API: Выставить счёт ссылкой и вернуть деньги

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

Ссылка на оплату без корзины на сайте и возврат по завершённой операции — оба через services.robokassa.ru, тело запроса — JWT.

1. Создай счёт: POST /InvoiceServiceWebApi/api/CreateInvoice. Payload — MerchantLogin, InvoiceType (OneTime или Reusable), OutSum, Description и при необходимости InvoiceItems для чека; подпиши его HMAC с секретом MerchantLogin:Пароль#1. В ответе url — ссылка для клиента.
2. Ответ приходит с HTTP 200 и при ошибках — проверяй isSuccess.
3. Для возврата подключи API возвратов в кабинете и получи Password3. Отправь POST /RefundService/Refund/Create с OpKey — идентификатором завершённой операции — и RefundSum для частичного возврата (для полного не передаётся). JWT подписывается Password3 алгоритмом HS256, HS384 или HS512.
4. Проверь результат возврата: GET /RefundService/Refund/GetState с id = requestId из ответа на создание. Ошибка 401 значит, что Password3 неверный или API возвратов не подключён.

import jwt, requests  # pip install pyjwt requests

token = jwt.encode({"OpKey": "<OpKey операции>", "RefundSum": 500.0}, "<Password3>", algorithm="HS256")
# Тело запроса — сама строка JWT
r = requests.post("https://services.robokassa.ru/RefundService/Refund/Create", data=token)
print(r.json())  # {"success": true, "requestId": "..."} — дальше Refund/GetState?id=<requestId>

Базовые URL

• Боевой (оплата, XML-интерфейсы, холдирование, рекурренты): https://auth.robokassa.ru
• Боевой (счета, возвраты, фискализация): https://services.robokassa.ru

Авторизация

Тип: Другое

Стандартной схемы авторизации нет: каждый запрос подписывается контрольной суммой, состав которой зависит от метода. В личном кабинете магазина берутся MerchantLogin, Пароль#1, Пароль#2 (и Password3 для API возвратов), там же выбирается алгоритм хэша (в примерах документации — MD5). Пароль#1 используется для подписи запросов на оплату, Пароль#2 — для проверки уведомлений и XML-интерфейсов. Invoice API и Refund API принимают тело в виде JWT, подписанного HMAC.

Подпись запуска оплаты: MerchantLogin:OutSum:InvId:модификаторы:Пароль#1:Shp_*. Пример из документации (PHP, MD5):

$signature = md5("$merchantLogin:$outSum:$invId:$password1");

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

POST /InvoiceServiceWebApi/api/CreateInvoice — Создать счёт

Создаёт одноразовую или многоразовую ссылку на оплату (хост services.robokassa.ru). Тело — строка JWT; секрет для HMAC — MerchantLogin:Пароль#1 (для тестового счёта с AdditionalParameters.IsTest=1 — тестовый Пароль#1). Ниже — поля payload.

Параметр	Где	Тип	Обяз.	Описание
MerchantLogin	body	string	да	Логин магазина
InvoiceType	body	string	да	OneTime или Reusable
Culture	body	string	нет	ru, en
InvId	body	integer	нет	Номер счёта
OutSum	body	number	нет	Сумма
ExpirationDate	body	string	нет	Окончание действия счёта
Description	body	string	нет	Описание
InvoiceItems	body	array	нет	Позиции для чека
Aliases	body	array	нет	Доступные способы оплаты
Sno	body	string	нет	Система налогообложения
AdditionalParameters	body	object	нет	Доп. параметры формы: IsTest, IncCurrLabel, PaymentMethods, Email, ResultURL2, StepByStep и др.

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

{"id":"01234567-89ab-4cde-8f01-23456789abcd","invId":1234567890,"url":"https://auth.robokassa.ru/merchant/Invoice/AbCdEfGhIjKlMnOpQrStUv","isSuccess":true}

POST /RefundService/Refund/Create — Создать возврат

Полный или частичный возврат по завершённой операции (хост services.robokassa.ru). Тело — JWT, подписанный Password3 (HS256, HS384 или HS512). Требует подключения API возвратов.

Пример ответа (ошибка 401):

Параметр	Где	Тип	Обяз.	Описание
OpKey	body	string	да	Идентификатор завершённой платёжной операции
RefundSum	body	number	нет	Сумма частичного возврата; для полного не передаётся
InvoiceItems	body	array	нет	Позиции чека возврата прихода

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

{"success":false,"message":"Signature key is not exists or partner have not access to API","requestId":null}

GET /RefundService/Refund/GetState — Состояние возврата

Параметр	Где	Тип	Обяз.	Описание
id	query	string	да	requestId, полученный при создании возврата

Нюансы

• После оплаты Robokassa отправляет на ResultURL поля OutSum, InvId, Fee, EMail, SignatureValue, PaymentMethod, IncCurrLabel и параметры Shp_*. Подпись проверяют по формуле OutSum:InvId:Пароль#2:Shp_* и только потом меняют статус заказа.
• Обработчик ResultURL должен ответить строкой OK + номер заказа (например OK12), иначе уведомление считается недоставленным.
• Пользовательские параметры с префиксом Shp_ возвращаются в уведомлениях без изменений и включаются в подпись в алфавитном порядке.
• При холдировании (StepByStep=true) в строку подписи добавляется модификатор true: MerchantLogin:OutSum:InvId:true:Пароль#1.
• Сумму передают с точностью до двух знаков после запятой, все данные — в UTF-8.
• Ошибка подписи обычно означает неверный порядок параметров или неверный пароль.
• XML-интерфейсы и Invoice API возвращают HTTP 200 и при прикладных ошибках; результат смотрят в Result.Code или isSuccess.
• OpStateExt, холдирование, рекурренты и возвраты не работают в тестовом режиме.
• У Robokassa есть публичный MCP-сервер для ИИ-ассистентов: https://mcp.robokassa.ru/

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

• Принять оплату через платёжную страницу
• Проверить, оплачен ли заказ
• Двухстадийная оплата: заблокировать и списать позже
• Повторные платежи по подписке

---

Если этого недостаточно — официальная документация: https://docs.robokassa.ru/ru/quick-start Вся интеграция одним документом: https://mcp-everything.ru/integrations/robokassa.md