# 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 возвратов не подключён.

```python
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 и др. |

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

```json
{"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://mcp-everything.ru/integrations/robokassa/scenarios/prinyat-oplatu-cherez-platezhnuyu.md)
- [Проверить, оплачен ли заказ](https://mcp-everything.ru/integrations/robokassa/scenarios/proverit-oplachen-li-zakaz.md)
- [Двухстадийная оплата: заблокировать и списать позже](https://mcp-everything.ru/integrations/robokassa/scenarios/dvuhstadiynaya-oplata-zablokirovat.md)
- [Повторные платежи по подписке](https://mcp-everything.ru/integrations/robokassa/scenarios/povtornye-platezhi-po-podpiske.md)

---

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