---
slug: "robokassa"
name: "Robokassa API"
vendor: "Robokassa"
industry: "finance"
docsUrl: "https://docs.robokassa.ru/ru/quick-start"
version: 2
updatedAt: "2026-10-24"
---

# Robokassa API

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

Платёжный сервис Robokassa: магазин перенаправляет покупателя на платёжную страницу с подписанными параметрами, а результат оплаты получает уведомлением на ResultURL. Отдельные интерфейсы позволяют выставлять счета-ссылки, проверять состояние операции, подтверждать и отменять холдирование, проводить повторные (рекуррентные) платежи и возвраты.

## Сценарии

### Принять оплату через платёжную страницу

Покупатель переходит на страницу Robokassa, платит и возвращается на сайт; магазин узнаёт об оплате серверным уведомлением.

1. В личном кабинете возьми MerchantLogin, Пароль#1 и Пароль#2, выбери алгоритм хэша (в примерах — MD5) и укажи ResultURL — адрес серверного уведомления.
2. Посчитай подпись: хэш строки MerchantLogin:OutSum:InvId:Пароль#1. Если передаёшь свои параметры Shp_*, добавь их в конец в алфавитном порядке в виде Shp_name=value.
3. Перенаправь покупателя: GET /Merchant/Index.aspx с MerchantLogin, OutSum (точка как разделитель, два знака), InvId, Description и SignatureValue. Для теста — IsTest=1 и тестовые пароли.
4. После оплаты Robokassa пришлёт на ResultURL OutSum, InvId и SignatureValue. Проверь подпись по формуле OutSum:InvId:Пароль#2[:Shp_*] и только после этого отметь заказ оплаченным.
5. Ответь на уведомление строкой OK + номер заказа (например, OK1042) — иначе Robokassa будет считать его недоставленным. Возврат покупателя на SuccessURL не подтверждает оплату.

```python
import hashlib
from urllib.parse import urlencode

LOGIN, PASS1, PASS2 = "demo-shop", "<Пароль#1>", "<Пароль#2>"

def pay_url(inv_id: int, out_sum: str, description: str) -> str:
    sig = hashlib.md5(f"{LOGIN}:{out_sum}:{inv_id}:{PASS1}".encode()).hexdigest()
    q = {"MerchantLogin": LOGIN, "OutSum": out_sum, "InvId": inv_id, "Description": description, "SignatureValue": sig}
    return "https://auth.robokassa.ru/Merchant/Index.aspx?" + urlencode(q)

def result_ok(form: dict) -> str | None:
    """Обработчик ResultURL: вернуть 'OK<InvId>' или None, если подпись неверна."""
    expected = hashlib.md5(f"{form['OutSum']}:{form['InvId']}:{PASS2}".encode()).hexdigest()
    return f"OK{form['InvId']}" if expected.lower() == form["SignatureValue"].lower() else None

print(pay_url(1042, "1500.00", "Оплата заказа 1042"))
```

### Проверить, оплачен ли заказ

Узнать состояние операции, если уведомление не пришло или нужно перепроверить.

1. Посчитай подпись: хэш строки MerchantLogin:InvoiceID:Пароль#2.
2. Запроси состояние: GET /Merchant/WebService/Service.asmx/OpStateExt с MerchantLogin, InvoiceID и Signature.
3. Ответ — XML. Сначала смотри Result/Code: 0 — запрос выполнен. Затем State/Code: 100 — операция оплачена.
4. Интерфейс работает только в боевом режиме: тестовые платежи он не возвращает.

```bash
SIG=$(printf '%s' 'demo-shop:1042:<Пароль#2>' | md5sum | cut -d' ' -f1)
curl -G https://auth.robokassa.ru/Merchant/WebService/Service.asmx/OpStateExt \
  -d MerchantLogin=demo-shop -d InvoiceID=1042 -d Signature=$SIG
```

### Двухстадийная оплата: заблокировать и списать позже

Деньги замораживаются при заказе, списываются после сборки или возвращаются при отмене.

1. Открой оплату с холдированием: GET /Merchant/Index.aspx с StepByStep=true. В подпись добавляется модификатор: MerchantLogin:OutSum:InvId:true:Пароль#1.
2. После оплаты операция окажется в состоянии HOLD — проверь это через OpStateExt.
3. Спиши деньги: POST /Merchant/Payment/Confirm с MerchantLogin, InvoiceID, OutSum и подписью MerchantLogin:OutSum:InvoiceID:Пароль#1. Вызывается один раз; новый Receipt может только уменьшить сумму и состав корзины.
4. Или отмени: POST /Merchant/Payment/Cancel. OutSum передаётся, но в подписи на месте суммы пустой сегмент: MerchantLogin::InvoiceID:Пароль#1.
5. Холдирование не работает в тестовом режиме.

```bash
SIG=$(printf '%s' 'demo-shop:1500.00:1042:<Пароль#1>' | md5sum | cut -d' ' -f1)
curl -X POST https://auth.robokassa.ru/Merchant/Payment/Confirm \
  -d MerchantLogin=demo-shop -d InvoiceID=1042 -d OutSum=1500.00 -d SignatureValue=$SIG
```

### Повторные платежи по подписке

Списывать деньги регулярно без участия покупателя после первой оплаты.

1. Первую (материнскую) оплату проведи как обычно через GET /Merchant/Index.aspx, добавив Recurring=true. Покупатель соглашается на повторные списания.
2. Для каждого следующего списания вызови POST /Merchant/Recurring с MerchantLogin, InvoiceID (новый номер операции), PreviousInvoiceID (номер оплаченной материнской операции), OutSum и подписью MerchantLogin:OutSum:InvoiceID:Пароль#1. PreviousInvoiceID в подпись не входит.
3. Ответ вида OK156 значит, что запрос принят; итог списания придёт уведомлением на ResultURL, как у обычной оплаты.
4. Повторные платежи работают только в боевом режиме.

```bash
SIG=$(printf '%s' 'demo-shop:399.00:2001:<Пароль#1>' | md5sum | cut -d' ' -f1)
curl -X POST https://auth.robokassa.ru/Merchant/Recurring \
  -d MerchantLogin=demo-shop -d InvoiceID=2001 -d PreviousInvoiceID=1042 \
  -d OutSum=399.00 --data-urlencode 'Description=Подписка, ноябрь' -d SignatureValue=$SIG
```

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

Ссылка на оплату без корзины на сайте и возврат по завершённой операции — оба через 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");
```

## Методы

### GET /Merchant/Index.aspx — Открыть платежную страницу

Создаёт операцию оплаты и открывает платёжную страницу. Тот же набор параметров можно отправить POST-формой (`application/x-www-form-urlencoded`). Для теста передайте `IsTest=1`. Ответ — HTML платёжной формы или 302 с адресом платёжной страницы; он не подтверждает оплату.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `MerchantLogin` | query | string | да | Идентификатор магазина |
| `OutSum` | query | string | да | Сумма к оплате, десятичный разделитель — точка |
| `SignatureValue` | query | string | да | Подпись запроса с Паролем#1 |
| `InvId` | query | integer | нет | Уникальный номер счёта; при 0 или отсутствии назначается автоматически |
| `Description` | query | string | нет | Название товара или услуги без спецсимволов |
| `Email` | query | string | нет | Email покупателя для чеков и уведомлений |
| `IncCurrLabel` | query | string | нет | Предлагаемый способ оплаты из GetCurrencies |
| `Culture` | query | string | нет | Язык платёжной страницы: ru, en |
| `Encoding` | query | string | нет | Кодировка данных |
| `IsTest` | query | integer | нет | Тестовый режим: 0, 1 |
| `ExpirationDate` | query | string | нет | Крайний срок оплаты, YYYY-MM-DDThh:mm |
| `Receipt` | query | string | нет | Фискальные данные — минимизированный JSON в URL-кодировке |
| `IsWithoutFreeSale` | query | boolean | нет | Не формировать автоматический чек «Свободная продажа» без Receipt |
| `StepByStep` | query | boolean | нет | Двухстадийная оплата (холдирование) |
| `PaymentMethods` | query | array | нет | Разрешённые способы оплаты, параметр можно повторять |
| `ResultUrl2` | query | string | нет | Дополнительный адрес серверного уведомления |
| `SuccessUrl2` | query | string | нет | Дополнительный адрес возврата после успешной оплаты |
| `FailUrl2` | query | string | нет | Дополнительный адрес возврата после ошибки |
| `Token` | query | string | нет | Токен сохранённой карты |
| `Recurring` | query | boolean | нет | Признак периодического платежа |

### GET /Merchant/WebService/Service.asmx/OpStateExt — Состояние операции

Возвращает состояние оплаты и реквизиты операции в XML. Работает только в основном режиме, тестовые платежи не возвращает. Подпись: `MerchantLogin:InvoiceID:Пароль#2`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `MerchantLogin` | query | string | да | Идентификатор магазина |
| `InvoiceID` | query | integer | да | Номер счёта магазина |
| `Signature` | query | string | да | Контрольная сумма в шестнадцатеричном формате |

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

```json
<OperationStateResponse>
  <Result><Code>0</Code></Result>
  <State>
    <Code>100</Code>
    <RequestDate>2026-07-22T10:00:00+03:00</RequestDate>
    <StateDate>2026-07-22T09:59:00+03:00</StateDate>
  </State>
</OperationStateResponse>
```

### GET /Merchant/WebService/Service.asmx/GetCurrencies — Доступные способы оплаты

Справочный метод без контрольной суммы.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `MerchantLogin` | query | string | да | Идентификатор магазина |
| `Language` | query | string | нет | Язык названий: ru, en |

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

```json
<CurrenciesList xmlns="http://merchant.roboxchange.com/WebService/">
  <Result><Code>0</Code></Result>
  <Groups>
    <Group Code="BankCard" Description="Банковской картой">
      <Items>
        <Currency Label="BankCardPSR" Alias="BankCard" Name="Банковская карта" />
      </Items>
    </Group>
  </Groups>
</CurrenciesList>
```

### 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 /Merchant/Payment/Confirm — Подтвердить списание при холдировании

Завершает двухстадийный платёж в состоянии HOLD. Вызывается один раз; новый `Receipt` может только уменьшить сумму и состав корзины. Подпись: `MerchantLogin:OutSum:InvoiceID:Пароль#1` (с чеком — `MerchantLogin:OutSum:InvoiceID:Receipt:Пароль#1`). Только основной режим.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `MerchantLogin` | body | string | да | Идентификатор магазина |
| `InvoiceID` | body | integer | да | Номер счёта |
| `OutSum` | body | string | да | Сумма |
| `Receipt` | body | string | нет | Обновлённый JSON чека в URL-кодировке |
| `SignatureValue` | body | string | да | Подпись |

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

```json
success: true
```

### POST /Merchant/Payment/Cancel — Отменить холдирование

Отменяет платёж в состоянии HOLD. `OutSum` передаётся, но в подписи вместо суммы пустой сегмент: `MerchantLogin::InvoiceID:Пароль#1`. Итоговый статус проверяют через OpStateExt.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `MerchantLogin` | body | string | да | Идентификатор магазина |
| `InvoiceID` | body | integer | да | Номер счёта |
| `OutSum` | body | string | да | Сумма (не входит в подпись) |
| `SignatureValue` | body | string | да | Подпись |

### POST /Merchant/Recurring — Повторный платёж

Дочерний платёж после успешной материнской операции с `Recurring=true`; списывает деньги без участия покупателя. `PreviousInvoiceID` в подпись не входит. Только основной режим.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `MerchantLogin` | body | string | да | Идентификатор магазина |
| `InvoiceID` | body | integer | да | Номер новой (дочерней) операции |
| `PreviousInvoiceID` | body | integer | да | Номер оплаченной материнской операции |
| `OutSum` | body | string | да | Сумма |
| `Description` | body | string | нет | Описание |
| `Receipt` | body | string | нет | JSON чека в URL-кодировке |
| `SignatureValue` | body | string | да | Подпись с Паролем#1 |

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

```json
OK156
```

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

## Ошибки

| Код | Описание |
|---|---|
| `400` | Refund API: некорректный JWT или невалидная подпись JWT |
| `401` | Refund API: неверный Password3 или API возвратов не подключён |
| `500` | Recurring: ошибка обработки рекуррентного платежа |

## Источники

- [OpenAPI-спецификация](https://docs.robokassa.ru/ru/api-specification)
- [Файл спецификации YAML](https://docs.robokassa.ru/openapi/robokassa.yaml)
- [Быстрый старт](https://docs.robokassa.ru/ru/quick-start)
- [Интерфейс оплаты](https://docs.robokassa.ru/ru/pay-interface)
- [Уведомления и переадресация](https://docs.robokassa.ru/ru/notifications-and-redirects)
- [Robokassa MCP](https://mcp.robokassa.ru/)

---

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