Платежи через PaySys.uz

Инструкция к модулю Платежи через PaySys.uz

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

Модуль добавляет в CS-Cart платёжный процессор PaySys.uz — универсальной системы приёма платежей в Узбекистане. Покупатель оформляет заказ в магазине, выбирает этот способ оплаты и завершает платёж на стороне PaySys.uz.

Модуль работает как внешний redirect-процессор: он собирает данные заказа, подписывает запрос и перенаправляет покупателя на платёжную страницу платёжной системы. В коде модуля нет обработчика, который принимает уведомления от PaySys.uz и автоматически меняет статус заказа после оплаты. Возвраты, холдирование (hold/capture) и фискализация в модуле также не реализованы.

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

Все настройки собраны в карточке способа оплаты:

1. Откройте Администрирование → Способы оплаты.

2. Создайте новый способ оплаты или откройте существующий способ оплаты PaySys.uz.

3. В поле выбора процессора укажите PaySys.uz — в списке процессоров он находится в группе MakeShop.pro.

4. Заполните параметры процессора и сохраните изменения.

Реквизиты доступа

В карточке способа оплаты заполняются поля, значения которых вы получаете от PaySys.uz.

Merchant ID (идентификатор магазина, VENDOR_ID) — основной идентификатор магазина (merchant ID) в платёжной системе. Модуль передаёт его в каждом платеже в поле VENDOR_ID. Без корректного Merchant ID платёжная система не сможет определить, в чей магазин направлен платёж, и оплата не пройдёт.

Client ID — в этом модуле отдельного поля Client ID нет. Идентификация магазина выполняется одним идентификатором — Merchant ID (в коде он называется VENDOR_ID), поэтому отдельное значение Client ID в карточку способа оплаты не вводится и модулем не используется. Если в кабинете PaySys.uz вам выдали Client ID, он нужен только для работы на стороне платёжной системы, а не для этого способа оплаты.

API токен (API-ключ) — секретное значение, которым подписывается запрос на оплату. Модуль строит подпись SIGN_STRING как MD5 от API токена, Merchant ID, номера заказа, суммы, валюты и времени подписи. Платёжная система проверяет эту подпись, поэтому API токен должен точно совпадать с выданным настройками, а менять его на рабочем магазине без необходимости не стоит.

Режим тестирования — переключает адрес платёжной страницы: рабочий https://agr.uz/pay или тестовый https://agr.uz/sandbox. В тестовом режиме используйте реквизиты, выданные PaySys.uz для песочницы.

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

1. Покупатель оформляет заказ и выбирает способ оплаты PaySys.uz.

2. CS-Cart создаёт заказ.

3. Модуль читает данные заказа и настройки способа оплаты.

4. В платёжную систему отправляются Merchant ID (VENDOR_ID), номер заказа, сумма, валюта sum, название способа оплаты, адрес возврата покупателя, время подписи и подпись SIGN_STRING.

5. Перед перенаправлением заказ переводится в статус Открыт, а корзина покупателя очищается.

6. Покупатель переходит на страницу PaySys.uz и завершает оплату там.

7. После оплаты покупатель возвращается в магазин на страницу завершения заказа.

Статусы, callback и webhook

В модуле нет настройки webhook/callback-адреса и нет обработчика, который принимает уведомление от PaySys.uz и сам меняет статус заказа после оплаты. Заказ переводится в статус Открыт до перехода покупателя на платёжную страницу, и этот статус остаётся у заказа после возврата покупателя в магазин.

Если по правилам PaySys.uz нужна сверка оплаты, её нужно организовать на стороне магазина: проверять оплату по данным платёжной системы и вручную переводить заказ в статус оплаты.

Возвраты, hold/capture и отмены

Модуль не реализует операции возврата, отмены, холдирования (hold), подтверждения (capture) или void из карточки заказа CS-Cart. Такие операции, если они доступны, выполняются вне модуля — в кабинете PaySys.uz или по процедурам платёжного провайдера.

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

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

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

1. Включите в карточке способа оплаты Режим тестирования.

2. Укажите тестовые Merchant ID и API токен, полученные от PaySys.uz.

3. Создайте тестовый заказ на витрине и выберите оплату PaySys.uz.

4. Убедитесь, что заказ создан в CS-Cart и получил статус Открыт.

5. Проверьте, что покупатель переходит на тестовую страницу https://agr.uz/sandbox.

6. После успешной проверки выключите тестовый режим и замените реквизиты на рабочие.