Robokassa API 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 не подтверждает оплату.
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. Интерфейс работает только в боевом режиме: тестовые платежи он не возвращает.
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. Холдирование не работает в тестовом режиме.
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. Повторные платежи работают только в боевом режиме.
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 возвратов не подключён.
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

Авторизация

Тип: Другое

Стандартной схемы авторизации нет: каждый запрос подписывается контрольной суммой, состав которой зависит от метода. В личном кабинете магазина берутся 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 да Контрольная сумма в шестнадцатеричном формате

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

<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

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

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

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

{"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 да Подпись

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

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

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

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, полученный при создании возврата

Нюансы

Ошибки

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

Источники

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