Robokassa API: ключи, подписи, webhooks и интеграция

Архитектура интеграции: редиректы, серверные уведомления

Классический поток: ваш сайт формирует параметры заказа и подпись, переадресует пользователя на страницу оплаты Robokassa. После оплаты Robokassa отправляет серверное уведомление (Result URL) на ваш бекенд и редиректит пользователя на Success/Fail URL. Ваша система должна доверять только Result URL, а не клиентскому редиректу.

![Схема взаимодействия с Robokassa API]

Ключи и подписи: как формируются и где хранить

В кабинете вы получаете логин мерчанта и секретные пароли/ключи для подписи. Подпись — хэш, формируемый из набора параметров (логин, сумма, номер заказа и секрет). Важно:

хранить секреты в переменных окружения/секрет‑хранилищах;
периодически ротировать ключи и отслеживать их использование;
не передавать секреты в клиентском коде.

Основные сценарии: создание счета, редирект на оплату, подтверждение

Создание счета: генерируете уникальный ID заказа, сумму, валюту, описание.
Редирект: формируете URL Robokassa с параметрами и подписью.
Подтверждение: принимаете webhook (Result URL), проверяете подпись, возвращаете «OK» и фиксируете оплату, затем показываете пользователю Success.

Result/Success/Fail URL и порядок обработки

Result URL — главный триггер. Обработка:

Проверить подпись и целостность параметров; 2) проверить сумму/валюту/ID; 3) отметить заказ как «оплачен»; 4) вернуть «OK» (строгое соответствие документации); 5) логировать событие. Success/Fail — для UX: показывают результат, но не меняют статус в БД.

Webhooks: повторные отправки, идемпотентность, логи

В случае тайм‑аута Robokassa может повторить уведомление. Реализуйте идемпотентность: обновляйте заказ только если статус изменился, используйте уникальные ключи/локи. Храните логи входящих уведомлений с заголовками и телом запроса, чтобы разбирать расхождения.

Тестовая среда и чек‑лист перед продом

Включите «тестовый режим» в кабинете.
Пройдите сценарии: успешная оплата, отказ, тайм‑аут, возврат.
Проверьте фискализацию (позиции, НДС, СНО, чек возврата).
Смоделируйте недоступность Result URL (повторы уведомлений).
Проверьте корректность Success/Fail UX.

Безопасность: секреты, SSL, журналирование

Включите HTTPS на всех URL.
Ограничьте доступ к Result URL по IP‑списку (если поддерживается) и проверке подписи.
Логируйте, но маскируйте персональные данные.
Мониторьте задержки webhook и ошибки подписи.

Типичные ошибки интеграции и их устранение

Неверная подпись — перепроверьте порядок параметров и типы (строка/число), используйте одну реализацию на бэкенде.
Несовпадение суммы/валюты — проверяйте округление и локаль.
Отсутствуют уведомления — проверьте DNS/SSL, фаервол и доступность Result URL.
Дубликаты — реализуйте идемпотентность обработки.

Готовые решения для CMS облегчат старт: см. Модули и плагины. Для UX и конверсии — подключите СБП и кошельки.