Инструкция к модулю Оплата через HUMO и UZCARD

Что делает модуль

Модуль добавляет в CS-Cart платёжный процессор «HUMO и UZCARD» для приёма оплат банковскими картами платёжных систем Узбекистана. Оплата проходит через JSON-RPC шлюз QRPay: в тестовом режиме используется http://testagent.qrpay.uz/api/jsonrpc, в рабочем режиме — https://agent.qrpay.uz/api/jsonrpc.

Платёжный сценарий построен через hold: после SMS-подтверждения сумма заказа резервируется на карте покупателя, а окончательное списание выполняется при переводе заказа в настроенный статус подтверждения.

Где находится модуль

Основная настройка режима находится в карточке модуля: Модули → Управление модулями → Оплата через HUMO и UZCARD. В разделе «Общее» доступен параметр Режим теста.

Параметры подключения задаются в способе оплаты: Администрирование → Способы оплаты, процессор HUMO и UZCARD. В блоке «Настройки шлюза» заполняются реквизиты терминала и статусы заказа.

Настройки модуля

Режим теста — если включён, модуль отправляет запросы на тестовый адрес шлюза и дополнительно пишет журнал запросов и ответов. Если выключен, используются рабочие адреса QRPay.

Настройки способа оплаты

Логин и Пароль — учётные данные для Basic Auth при обращении к шлюзу.

ID терминала — идентификатор терминала, выданный платёжным провайдером.

Номер мерчанта — merchant ID магазина в платёжной системе.

Название терминала и Порт — технические параметры регистрации терминала. В интерфейсе они скрыты и по умолчанию заполняются случайным значением, если ранее не были сохранены.

Статус оплаченного заказа — статус, который получает заказ после успешной проверки SMS-кода и создания hold.

Статус подтвержденного заказа — статус, при переходе в который модуль выполняет списание средств из hold.

Статус терминала — результат проверки терминала в шлюзе. Если терминал не зарегистрирован, модуль показывает кнопку регистрации.

Регистрация и проверка терминала

После заполнения логина, пароля, ID терминала и номера мерчанта модуль автоматически проверяет терминал запросом terminal.check. Если шлюз отвечает успешно, поле статуса показывает «Зарегистрирован».

Если терминал не найден, становится доступна кнопка «Зарегистрировать». Она отправляет запрос terminal.add с данными терминала, мерчанта, порта и названия терминала.

Как проходит оплата

Покупатель выбирает способ оплаты HUMO и UZCARD и вводит данные карты. Модуль отправляет запрос на токенизацию карты и инициирует SMS-подтверждение.

После ввода SMS-кода модуль проверяет код через шлюз. При успешной проверке он получает баланс по токену карты, сравнивает его с суммой заказа и создаёт hold на сумму заказа. Сумма передаётся в тийинах — модуль умножает сумму заказа на 100.

Если hold создан успешно, заказ получает статус из настройки «Статус оплаченного заказа», а идентификатор hold сохраняется в параметрах способа оплаты.

Подтверждение списания

Когда заказ переводится в статус, выбранный в настройке «Статус подтвержденного заказа», модуль отправляет запрос hold.dismiss.charge. После успешного ответа hold удаляется из параметров оплаты, а средства считаются списанными.

Возвраты

Если у платежа есть активный hold, в карточке заказа появляется кнопка «Вернуть средства клиенту». При подтверждении модуль отправляет запрос hold.dismiss, удаляет hold из параметров оплаты, переводит заказ в статус «Отменён» и добавляет запись в журнал заказа.

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

Webhook и callback

Внешний webhook от платёжной системы в модуле не настраивается. Callback используется внутри CS-Cart для страницы ввода SMS-кода: покупатель отправляет код на URL вида payment_notification.frame, после чего CS-Cart завершает оформление заказа.

Чеки и фискализация

В коде модуля нет отдельных настроек фискализации, 54-ФЗ или DigitalKassa. Если магазину нужны чеки, используйте отдельную фискальную интеграцию CS-Cart и проверьте требования платёжного провайдера.

Журналы и диагностика

При ошибках шлюза модуль пишет данные в файл app/addons/ms_humo_uzcard/Tygh/Addons/MsHumoUzcard/logs/error_log.txt. В тестовом режиме дополнительно пишется файл resp_req_log.txt с запросами и ответами.

Если платёж не проходит, проверьте режим работы, логин, пароль, ID терминала, номер мерчанта, статус регистрации терминала и ответ шлюза в журнале.

Как проверить работу

Включите тестовый режим, заполните реквизиты способа оплаты и убедитесь, что терминал получил статус «Зарегистрирован».

Создайте тестовый заказ и оплатите его способом HUMO и UZCARD. Проверьте, что покупателю показана форма ввода SMS-кода, после успешного ввода заказ получает выбранный статус оплаченного заказа, а в данных оплаты сохраняется transaction ID/hold ID.

Переведите заказ в статус подтверждения и убедитесь, что модуль выполнил списание из hold. Для проверки отмены создайте новый заказ с активным hold и используйте кнопку «Вернуть средства клиенту» до подтверждения списания.