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