Top.Mail.Ru
  • CMS «ГИРВАС»

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

    С нами проще!

  • Абсолютно бесплатно

    Хватит использовать старые и платные системы управления! Настала эпоха новых решений - выбирайте «GIRVAS»!

  • Карельское решение

    «ГИРВАС» разработана в Республике Карелия, а также внесена в Реестр российского программного обеспечения Министерством цифрового развития Российской Федерации (реестровая запись №25012 от 27.11.2024).

Установка и настройка модуля RBConnect для CMS «ГИРВАС»: интеграция с Робокассой

Модуль RBConnect представляет собой служебный компонент CMS «ГИРВАС», который обеспечивает прием оплаты через платежный шлюз Робокасса для других модулей сайта. Сам по себе RBConnect ничего не продает: модуль-заказчик (например, каталог услуг или интернет-магазин) передает ему информацию о заказе, а RBConnect выставляет счет, перенаправляет покупателя на страницу оплаты, проверяет уведомление об успешной транзакции и передает состав чека для системы Робочеков.

В данном руководстве мы подробно рассмотрим процесс установки модуля, его настройку, работу с тестовым режимом, настройку фискализации, а также разберем особенности фоновой работы и управления счетами. Статья ориентирована на администраторов сайтов и веб-разработчиков, обслуживающих проекты на CMS «ГИРВАС».

Требования и подготовка к установке

Перед началом установки модуля RBConnect убедитесь, что ваш сервер соответствует следующим требованиям:

  • CMS «ГИРВАС» версии 0.4.x.
  • PHP 8.1+ с расширениями pdo, json, mbstring. Для работы функции сверки счетов также потребуются расширения curl и simplexml.
  • Поддерживаемые СУБД: PostgreSQL и MySQL (MariaDB).
  • Наличие действующего аккаунта в Робокассе с настроенным магазином.

Модуль поддерживает русский и английский интерфейсы, что делает его удобным для использования в многоязычных проектах.

Установка модуля

Процесс установки RBConnect стандартен для модулей CMS «ГИРВАС»:

  1. Загрузка файлов: Распакуйте архив с модулем в папку modules/ вашего сайта. В результате должна появиться директория modules/rbconnect.
  2. Активация: Перейдите в Админ-Центр → «Модули» → «RBConnect» → нажмите кнопку «Активация». Таблицы базы данных будут созданы автоматически при первом обращении к модулю.
  3. Открытие раздела: На странице модуля нажмите кнопку «Открыть раздел», чтобы перейти к интерфейсу управления RBConnect.

Настройка магазина в Робокассе

Первым шагом после установки является настройка интеграции с вашим магазином в Робокассе.

Получение ключей доступа

В личном кабинете Робокассы перейдите в раздел «Мои магазины» → выберите нужный магазин → «Технические настройки». Здесь вам потребуется скопировать следующие данные:

  • Идентификатор магазина (Merchant Login).
  • Пароль № 1 (используется для подписи ссылок на оплату).
  • Пароль № 2 (используется для проверки уведомлений Result URL).

Эти данные необходимо ввести в разделе модуля «Настройки» → «Магазин».

Настройка алгоритма подписи

В настройках модуля выберите тот же алгоритм расчета хеша, который установлен в личном кабинете Робокассы. Модуль поддерживает алгоритмы MD5, RIPEMD-160, SHA-1, SHA-256, SHA-384 и SHA-512.

Настройка URL-адресов в кабинете Робокассы

В кабинете Робокассы в технических настройках магазина укажите адреса, которые сгенерированы в разделе модуля «Подключение»:

  • Result URL: https://ваш-сайт/handler/module-rbconnect/result — для проверки уведомлений об оплате.
  • Success URL: https://ваш-сайт/handler/module-rbconnect/success — для возврата покупателя после успешной оплаты.
  • Fail URL: https://ваш-сайт/handler/module-rbconnect/fail — для возврата покупателя при отказе от оплаты.

Метод отправки уведомлений может быть любым (POST или GET), модуль корректно обрабатывает оба варианта.

Безопасность: пароли в форме настроек не отображаются. Если оставить поле пустым, сохранится текущий пароль. Для удаления пароля предусмотрен специальный флажок «Стереть». Пароли и подписи никогда не записываются в журналы.

Тестовый режим

По умолчанию модуль работает в тестовом режиме. Это позволяет безопасно проверить интеграцию без списания реальных денежных средств.

В технических настройках магазина в Робокассе предусмотрен блок с тестовыми паролями. Скопируйте их в разделе модуля «Настройки» → «Тестовый режим».

Пока тестовый режим включен:

  • Все счета уходят в Робокассу с параметром IsTest=1.
  • Деньги не списываются.
  • На странице оплаты отображается пометка «Тестовый платеж».

Важно: перед запуском проекта в эксплуатацию обязательно выключите тестовый режим. Счета, созданные в тестовом режиме, после переключения на боевой режим не открываются — модулю-заказчику потребуется оформить новый заказ.

Настройка чеков (Робочеки)

Для соответствия требованиям законодательства о применении контрольно-кассовой техники (54-ФЗ) модуль RBConnect поддерживает передачу данных для формирования чеков.

Перед настройкой чеков в модуле необходимо подключить фискализацию в личном кабинете Робокассы (раздел «Фискализация»).

В разделе модуля «Настройки» → «Чеки» доступны следующие параметры:

  • Как выдаются чеки: выберите один из вариантов — «Робочеки (ИП и организации)», «Робочеки СМЗ» (для самозанятых, где ставка всегда «без НДС», а система налогообложения не передается), «Облачная касса» или «Своя касса».
  • Система налогообложения: можно указать «как в личном кабинете» или выбрать явно.
  • Ставка НДС: укажите применимую ставку.
  • Способ расчета: для услуг, оказываемых сразу, выбирается «полный расчет».
  • Предмет расчета по умолчанию: модуль-заказчик может указать свой предмет расчета для каждой позиции.

Чек собирается в момент создания счета и в дальнейшем не изменяется. Сумма позиций чека всегда равна сумме счета. Модуль не формирует второй чек (зачет предоплаты). Если чеки в вашем магазине не подключены, отключите опцию «Передавать чек».

Проверка подключения

После ввода ключей рекомендуется проверить их корректность. В разделе «Подключение» нажмите кнопку «Проверить ключи». Модуль отправит запрос в Робокассу о состоянии несуществующего счета с использованием боевого пароля № 2. Если в ответ придет сообщение «счет не найден», это означает, что идентификатор магазина и пароль указаны верно.

Обратите внимание: тестовые пароли таким способом проверить нельзя. Для их проверки необходимо провести тестовый платеж.

Фоновая работа и сверка счетов

Модуль RBConnect оснащен механизмом фоновой работы, который обеспечивает надежность приема платежей.

Раз в 5 минут модуль сверяет неоплаченные боевые счета с Робокассой (до 20 счетов за раз). Это необходимо на случай, если уведомление об оплате не дошло до сайта. Кроме того, фоновая задача отмечает счета с истекшим сроком оплаты и стирает старые адреса электронной почты.

Фоновая работа запускается автоматически после ответа на запросы модуля (переход к оплате, уведомления Робокассы, открытие раздела Админ-Центра). Посетители сайта не ждут выполнения этих операций.

На хостингах без PHP-FPM ответ отправляется только после завершения фоновой работы. В таких случаях она выполняется лишь после открытия раздела в Админ-Центре, занимает не более 2 секунд и не включает сверку с Робокассой. Для полноценной работы сверки на подобных хостингах рекомендуется добавить задачу в cron:

0-59/5 * * * * php /путь/к/сайту/modules/rbconnect/cron/reconcile.php --quiet

Управление счетами

Раздел управления счетами Robokassa в административной панели CMS «ГИРВАС»
Раздел управления счетами Robokassa в административной панели CMS «ГИРВАС»

Раздел «Счета» в Админ-Центре предоставляет полный обзор всех платежей, проходящих через модуль RBConnect. Здесь администраторы могут отслеживать статусы заказов, анализировать финансовые показатели и при необходимости вмешиваться в процесс оплаты.

Сводная статистика

В верхней части раздела «Счета» отображаются ключевые показатели за последние 30 дней:

  • Получено за 30 дней (без тестовых) — общая сумма успешных оплат, исключая тестовые платежи.
  • Оплачено счетов — количество счетов, по которым поступила оплата.
  • Ждут оплаты — количество счетов, созданных, но еще не оплаченных покупателями.
  • Последнее уведомление Робокассы — дата и время последнего полученного уведомления от платежного шлюза.

Эти данные позволяют быстро оценить текущее состояние платежной системы и активность покупателей.

Фильтрация и поиск

Для удобства работы с большим количеством счетов предусмотрены различные инструменты фильтрации:

  • Фильтр по статусу — доступны кнопки быстрого переключения: «Все», «Ждет оплаты», «Оплачен», «Отказ от оплаты», «Истек», «Отменен».
  • Фильтр по модулю — выпадающий список, позволяющий отобразить счета, созданные конкретным модулем-заказчиком (например, «gameservers» или «Любой»).
  • Поиск по номеру счета или заказа — текстовое поле для быстрого поиска конкретной транзакции.

После выбора параметров фильтрации необходимо нажать кнопку «Найти» для применения условий.

Статусы счетов

Каждый счет в журнале имеет один из следующих статусов:

  • Ждет оплаты — счет создан, покупатель перешел к оплате, но транзакция еще не завершена.
  • Оплачен — Робокасса подтвердила оплату (уведомление с верной подписью и суммой или сверка). Это окончательный статус, счет не может быть изменен.
  • Отказ от оплаты — покупатель вернулся со страницы оплаты без совершения платежа. Оплатить такой счет можно снова по той же ссылке.
  • Истек — счет не был оплачен в течение срока, указанного в настройке «Срок оплаты счета» (по умолчанию 3 дня).
  • Отменен — счет отменен администратором вручную.

Важно: оплата, пришедшая позже срока или после отмены, все равно принимается, так как деньги уже списаны. Модуль-заказчик увидит, что счет оплачен, и сможет корректно обработать заказ.

Таблица счетов

Основная часть раздела представляет собой таблицу со следующими колонками:

  • Счет — порядковый номер счета в системе.
  • Создан — дата и время создания счета.
  • Заказ — идентификатор заказа в модуле-заказчике (например, GS-261110-B97B9CA3).
  • Описание — текстовое описание заказа или услуги.
  • Сумма — стоимость заказа в рублях.
  • Статус — текущий статус счета (с цветовой индикацией для удобства).
  • Оплачен — дата и время оплаты (если счет оплачен).

Для тестовых счетов в таблице отображается специальная метка «тест», позволяющая отличить их от боевых транзакций.

Карточка счета

При клике на номер счета открывается детальная карточка, содержащая полную информацию о транзакции:

  • Данные о заказе и модуле-заказчике.
  • Состав чека (если включена передача чеков).
  • Журнал событий по счету (создание, переход к оплате, уведомления от Робокассы, сверка и т.д.).
  • Кнопка отмены неоплаченного счета (доступна только для счетов в статусе «Ждет оплаты»).

Отмена счета

Администратор с правом rbconnect.manage_payments может отменить неоплаченный счет. После отмены счет переходит в статус «Отменен», и покупатель больше не может его оплатить. Однако, как упоминалось ранее, если оплата уже была произведена, но уведомление задержалось, деньги все равно будут приняты, а счет автоматически перейдет в статус «Оплачен».

Нумерация счетов

Номер счета в Робокассе формируется как сумма «Сдвига номеров счетов» (настраивается в разделе «Настройки» → «Магазин») и порядкового номера счета в системе.

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

Рекомендации по работе с разделом

  • Регулярно проверяйте счета в статусе «Ждет оплаты» — если покупатель не завершил оплату, можно связаться с ним для уточнения причин.
  • Используйте фильтр по модулю для анализа эффективности различных услуг или товаров.
  • При возникновении спорных ситуаций обращайтесь к журналу событий в карточке счета — он содержит полную историю взаимодействия с Робокассой.
  • Не отменяйте счета без необходимости: если покупатель еще может оплатить заказ, отмена может привести к потере клиента.

Раздел «Счета» является центральным элементом контроля за платежами в модуле RBConnect, предоставляя все необходимые инструменты для мониторинга и управления финансовыми операциями на сайте.

Подключение нескольких модулей

Модуль RBConnect спроектирован как универсальное платежное ядро. Любой модуль сайта может подключиться к нему через публичный интерфейс PublicPayments (подробности описаны в файле DEVELOPMENT.md), при этом код самого RBConnect менять не нужно. Это позволяет использовать один экземпляр модуля для приема оплаты сразу в нескольких независимых частях сайта.

Например, каталог платных услуг и интернет-магазин могут принимать оплату одновременно. При этом соблюдаются следующие принципы:

  • Изоляция заказов: каждый модуль передает свое имя (consumer) и свои номера заказов. Заказы разных модулей не пересекаются, даже если их номера совпадают. Это исключает путаницу при обработке платежей.
  • Гибкость возврата: каждый модуль самостоятельно задает, куда вернуть покупателя после оплаты, и сам решает, что выдать после успешной транзакции (например, доступ к услуге, электронный товар или изменение статуса заказа).
  • Фильтрация в журнале: в разделе «Счета» Админ-Центра предусмотрен фильтр по модулю, что позволяет администратору быстро находить платежи конкретного сервиса.

Общими для всех модулей-заказчиков остаются:

  • магазин Робокассы (идентификатор и пароли);
  • режим работы (тестовый или боевой);
  • настройки чеков (система налогообложения, ставка НДС, способ расчета).

Модуль-заказчик может указать предмет расчета для своей позиции самостоятельно, но не может изменить систему налогообложения и ставку НДС — эти параметры задаются глобально в настройках RBConnect.

Права доступа

Раздел управления правами Robokassa в административной панели CMS «ГИРВАС»

Модуль RBConnect использует собственную систему прав, которые можно гибко назначать группам пользователей панели. Это позволяет разграничить зоны ответственности между администраторами, бухгалтерами и техническими специалистами.

Право Что дает
rbconnect.view_payments Видеть счета и журнал событий
rbconnect.manage_payments Сверять и отменять счета
rbconnect.manage_settings Менять настройки магазина, чеков и права

По умолчанию все права назначены группе 1 (администраторы). Группы с правом суперпользователя CMS могут выполнять любые действия в модуле. Снять у своей группы право менять права нельзя — это защита от случайной блокировки доступа к настройкам.

Внешние сервисы и персональные данные

Модуль RBConnect обращается только к сервисам Робокассы:

  • https://auth.robokassa.ru/Merchant/Index.aspx — страница оплаты, куда браузер покупателя отправляет данные счета и чека;
  • https://auth.robokassa.ru/Merchant/WebService/Service.asmx/OpStateExt — запрос состояния счета с сервера сайта (используется для сверки и проверки ключей).

Других сторонних сервисов, скриптов, шрифтов и CDN нет.

Персональные данные и 152-ФЗ

В рамках соблюдения Федерального закона № 152-ФЗ «О персональных данных» модуль хранит в счете:

  • ID пользователя CMS;
  • адрес электронной почты (если его передал модуль-заказчик) — для отправки чека;
  • сумму, состав чека и время событий.

Почта передается в Робокассу для отправки чека и стирается из счета фоновой задачей через указанный срок (по умолчанию 30 дней, настройка «Хранить почту покупателя, дней»).

Платежные данные (номер карты и т.п.) модуль не получает. IP-адреса покупателей не сохраняются; адрес нужен только для ограничения частоты запросов и хранится как HMAC в имени временного файла.

Что сделать оператору сайта:

  1. Указать Робокассу как получателя данных в политике обработки персональных данных.
  2. Опубликовать оферту и правила возврата.
  3. Определить срок хранения счетов (это записи об оплате; модуль их не удаляет).
  4. Согласовать порядок обработки данных с юристом — модуль не делает сайт соответствующим 152-ФЗ автоматически.

Обновление и удаление модуля

Обновление

Для обновления модуля распакуйте новую версию поверх директории modules/rbconnect. При обновлении до версии 1.1.0 необходимо удалить файл styles/robokassaconnect.css.

Данные не меняются. Версия схемы БД теперь хранится в cache/modules/rbconnect/schema-version и в записи module_rbconnect_schema таблицы настроек. Старый файл .schema-version в папке модуля можно не трогать — модуль его читает для обратной совместимости.

Удаление

Для удаления модуля:

  1. Выключите его в Админ-Центре.
  2. Удалите папку modules/rbconnect.
  3. Счета остаются в таблицах [префикс_]module_rbconnect_payments и _events, настройки — в записях module_rbconnect_settings и module_rbconnect_schema таблицы настроек. Удалите их вручную, когда истечет срок хранения записей об оплате.
  4. Папку cache/modules/rbconnect можно удалить.

Ограничения модуля

При использовании RBConnect следует учитывать следующие ограничения:

  • Второй чек (зачет предоплаты), возвраты и рекуррентные платежи не поддерживаются. Возврат делается в кабинете Робокассы.
  • Сверка (OpStateExt) работает только для боевых счетов — так устроена Робокасса.
  • Валюта — только рубли.
  • Модуль-заказчик узнает об оплате, читая состояние своих заказов (см. DEVELOPMENT.md); мгновенного вызова кода модуля-заказчика нет.

Заключение

Модуль RBConnect является мощным и гибким инструментом для организации приема онлайн-платежей на сайте под управлением CMS «ГИРВАС». Благодаря поддержке Робочеков, тестового режима, фоновой сверки счетов и возможности подключения нескольких модулей-заказчиков, он позволяет построить надежную и соответствующую законодательству систему оплаты.

При настройке модуля уделите особое внимание корректности ввода ключей доступа, настройке URL-адресов в кабинете Робокассы и параметров фискализации. Перед запуском в production обязательно проведите тестирование в тестовом режиме и проверьте работу фоновых задач, особенно на хостингах без PHP-FPM, где может потребоваться настройка cron.

Соблюдение всех рекомендаций позволит вам обеспечить бесперебойный прием платежей и удобство для ваших клиентов.

Robokassa
Robokassa
Robokassa — платёжный агрегатор, который помогает бизнесу принимать онлайн-платежи. Сервис ориентирован на ИП, юридические лица и самозанятых, работающих в сфере электронной коммерции, услуг, онлайн-образования, доставки, туризма, цифровых товаров и других отраслей. Работает в России и Казахстане.
Переводы

Комментарии

К этой записи нет комментариев.