Архитектура и ключевые сущности
В основе Robokassa API — три ключевые сущности:
- Платеж (Payment): инициируется вашим магазином и оплачивается клиентом. Подробнее о сценариях — в разделе Платежи.
- Чек (Receipt): фискальный документ с номенклатурой, НДС и признаками расчета. Подробно — в разделе Чеки.
- Уведомление (Webhook): асинхронный обратный вызов на ваш сервер о смене статуса платежа.
Обычно поток выглядит так:
- Магазин формирует заказ, считает подпись Robokassa и перенаправляет клиента на платежную форму.
- Клиент платит выбранным методом (карта, СБП и т. п.) — это инфраструктура интернет-эквайринга (см. Интернет‑эквайринг).
- Robokassa отправляет webhook на ваш Result URL с параметрами оплаты и контрольной подписью.
- Ваш сервер проверяет подпись, проводит заказ и возвращает «OK».
- Опционально формируется чек и отправляется клиенту.
Основные методы: инициация, статус, возврат
Типовой набор взаимодействий с robokassa api:
Пример ключевых параметров при инициации:
| Параметр |
Назначение |
| MerchantLogin |
Логин магазина в Robokassa |
| OutSum |
Сумма оплаты (десятичная строка) |
| InvId |
ID заказа в вашей системе (уникальный номер) |
| Description |
Описание заказа (для клиента) |
| Email/Phone |
Контакты покупателя |
| Culture |
Локаль интерфейса платежной формы |
| Shp_* |
Пользовательские поля, возвращаются в webhook |
| SignatureValue |
Контрольная подпись Robokassa |
Подпись Robokassa: формирование и проверка
Подпись Robokassa — главный механизм защиты целостности данных. Ее задача — гарантировать, что параметры не были изменены на пути от вашего сервера до шлюза и обратно.
Ключевые факты:
- Алгоритм подписи выбирается в ЛК (часто используется SHA‑256; встречается MD5). Уточняйте настройки в Личном кабинете.
- Обычно применяются две секции секретов: Password1 (для формирования ссылки/инициации) и Password2 (для проверки Result URL).
- Пользовательские параметры, начинающиеся с shp_, почти всегда включаются в строку подписи. Порядок важен.
Упрощенная схема (пример, не подменяет официальную документацию):
- Подпись при инициации: hash(MerchantLogin:OutSum:InvId:Password1[:shp_*…])
- Подпись в webhook (Result URL): hash(OutSum:InvId:Password2[:shp_*…])
Рекомендации по безопасности:
- Никогда не рассчитывайте подпись на клиенте — только на сервере.
- Приводите регистр подписи к нижнему/верхнему согласно настройкам; часто сравнивают в нижнем регистре.
- Храните пароли/ключи только в защищенных переменных окружения.
Мини‑пример на Python (SHA‑256):
import hashlib
def sign_initiate(merchant_login, out_sum, inv_id, password1, shp_params=None):
parts = [merchant_login, f"{out_sum}", str(inv_id), password1]
if shp_params:
## Включайте shp_* в порядке ключей по алфавиту, если это требуется в настройках вашей схемы подписи
for k in sorted(shp_params):
parts.append(f"{k}={shp_params[k]}")
raw = ":".join(parts)
return hashlib.sha256(raw.encode('utf-8')).hexdigest()
Webhook Robokassa (Result URL): структура, повторные уведомления, безопасность
Webhook Robokassa — это серверный запрос на ваш Result URL, который сообщает о статусе оплаты. Его необходимо валидировать по подписи и параметрам.
Что приходит в webhook (набор параметров может отличаться):
| Поле |
Описание |
| OutSum |
Итоговая сумма платежа |
| InvId |
Ваш ID заказа |
| SignatureValue |
Подпись robokassa для проверки |
| Shp_* |
Пользовательские параметры, если передавались |
| Доп. поля |
Могут включать метод оплаты, валюту и др. |
Практика обработки:
- Логируйте весь запрос (без секретов) для отладки.
- Восстановите строку для подписи и проверьте SignatureValue (используйте Password2).
- Проверьте соответствие суммы и валюты заказу, убедитесь, что платеж еще не обработан (идемпотентность).
- Проведите заказ в своей системе.
- Верните HTTP 200 и «OK» (или требуемую строку подтверждения) — формат ответа смотрите в документации вашего ЛК.
Повторы: webhook может прийти несколько раз (сетевые задержки, ретраи). Поэтому ваш обработчик должен быть идемпотентным: повторная обработка одного и того же InvId не должна дублировать списания/проводки.
Безопасность:
- Проверяйте только подпись и деловую логику; доверять IP‑адресам без проверки подписи нельзя. При этом актуальные подсети провайдера обычно публикуются в ЛК.
- Принимайте Result URL только по HTTPS.
Идемпотентность Robokassa: практики и антидублирование
Идемпотентность Robokassa — это стратегия, позволяющая безопасно обрабатывать повторные запросы и уведомления, не создавая дублей транзакций. Что стоит сделать:
- Уникальный ключ: используйте InvId (ваш OrderID) как уникальный ключ операции.
- Таблица состояний: храните статусы платежа (new, paid, refunded) и флаг «проведен».
- Защита от гонок: оборачивайте обработку webhook в транзакцию БД и «select for update» по InvId.
- Повторные вызовы: если уведомление пришло повторно, проверяйте статус — при paid просто верните OK без повторной логики.
- Контроль суммы: проверяйте OutSum на соответствие заказу, чтобы исключить подмену.
Если API провайдера поддерживает RequestId/Idempotency-Key в заголовке — используйте. В противном случае достаточно грамотно работать с InvId и транзакциями.
Пример API Robokassa: ссылки и код
Ниже — нейтральные примеры, иллюстрирующие общий принцип. Базовые URL уточняйте в вашем ЛК.
Формирование ссылки на оплату (redirect):
## ВАЖНО: используйте URL платежной формы из вашей документации в ЛК
PAY_URL="https://auth.robokassa.ru/Merchant/Index.aspx"
## Пример cURL (GET-параметры)
curl -G "$PAY_URL" \
--data-urlencode "MerchantLogin=demo-shop" \
--data-urlencode "OutSum=1990.00" \
--data-urlencode "InvId=12345" \
--data-urlencode "Description=Оплата заказа №12345" \
--data-urlencode "[email protected]" \
--data-urlencode "shp_user=42" \
--data-urlencode "SignatureValue=3f5a...d1"
Проверка подписи в webhook на PHP (пример):
<?php
function verifyWebhook($outSum, $invId, $signatureValue, $password2, $shpParams = []) {
ksort($shpParams); // если ваша схема подписи требует сортировки shp_*
$parts = [$outSum, $invId, $password2];
foreach ($shpParams as $k => $v) {
$parts[] = "$k=$v";
}
$raw = implode(":", $parts);
$calc = strtolower(hash('sha256', $raw));
return strtolower($signatureValue) === $calc;
}
?>
Мини‑сервер на Node.js (Express) для приема webhook:
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.urlencoded({ extended: true }));
app.post('/result', (req, res) => {
const { OutSum, InvId, SignatureValue, ...rest } = req.body;
const shp = Object.fromEntries(Object.entries(rest).filter(([k]) => k.startsWith('shp_')));
const password2 = process.env.RB_PWD2;
const parts = [OutSum, InvId, password2];
Object.keys(shp).sort().forEach(k => parts.push(`${k}=${shp[k]}`));
const raw = parts.join(':');
const calc = crypto.createHash('sha256').update(raw).digest('hex');
if (calc !== String(SignatureValue).toLowerCase()) {
return res.status(400).send('bad sign');
}
// идемпотентная обработка InvId ...
// conduct order here
return res.status(200).send('OK');
});
app.listen(3000);
Тестовый режим и фискальные чеки
- Тестовый магазин: в ЛК обычно выдается отдельный логин и две «пароли» (Password1/Password2) для тестовой витрины. Не путайте их с боевыми.
- Проверка чеков: в тестовом режиме формируйте номенклатуру с корректными ставками НДС, признаками способа расчета. Это упростит переход на прод.
- Обязательные поля для чека: наименование, цена, количество, ставка НДС, предмет расчета. Подробнее см. Чеки.
Частые ошибки и отладка
- Некорректная подпись robokassa: проверьте порядок полей, алгоритм (SHA‑256 vs MD5), регистр и участие shp_* в подписи.
- Несовпадение суммы: передавайте денежные суммы в одном формате (строка с двумя знаками после запятой).
- Дублирование проводки: сделайте идемпотентность на уровне БД/транзакций.
- Webhook не приходит: убедитесь, что ваш Result URL доступен по HTTPS из внешней сети; проверьте логирование и firewall.
- Неверный ответ Result URL: возвращайте именно ту строку/статус, которую требует документация, иначе Robokassa будет повторять уведомления.
Для вопросов — загляните в FAQ или свяжитесь через телефон службы поддержки.
Интеграции и полезные ссылки
- Быстрый старт и подключение: страница Подключить.
- О приемах платежей и сценариях — раздел Платежи.
- Кассовая фискализация чеков — раздел Чеки.
- Интеграция с 1С — готовые подходы и советы на странице 1С интеграция.
- Подробная API‑справка — эта страница API документация.
Итоги и как подключить
Robokassa API позволяет быстро запустить прием онлайн‑платежей: от генерации безопасной ссылки до приема webhook и автоматической фискализации. Соблюдайте правила подписи Robokassa, делайте обработчики идемпотентными и не считайте секреты на клиенте — это обеспечит надежность и предсказуемость платежного потока.
Готовы принять первый платеж? Перейдите к подключению интернет‑эквайринга на странице Подключить и оформите интеграцию. Если остались вопросы, изучите FAQ или уточните детали на официальном сайте.
