5. Платёжные методы

RUSTCMS поддерживает множество популярных платежных систем. Все настройки производятся через панель администратора в разделе Платежи.

Общая настройка

1. Перейдите в админ-панель: /admin/payments.
2. Выберите нужного провайдера из списка (нажмите на карточку).
3. Заполните необходимые ключи (Merchant ID, Secret Key и др.).
4. Нажмите кнопку Сохранить настройки.
5. После сохранения включите галочку Включить приём платежей и убедитесь, что индикатор "Провайдер" активен.

Примечание: Ключи сохраняются в файл config/local.php. Не передавайте этот файл третьим лицам.

Включение провайдеров и флаги

Отображение методов оплаты на страницах Checkout и Order зависит от флагов включения:

• PAYMENTS_ENABLED — включает приём платежей в целом.
• YOOMONEY_ENABLED — включает ЮMoney.
• UNITPAY_ENABLED — включает UnitPay.
• FREEKASSA_ENABLED — включает FreeKassa.
• ENOT_ENABLED — включает ENOT.io.

Флаги задаются автоматически при сохранении формы в /admin/payments и попадают в config/local.php. По умолчанию (в config/config.php) они равны false.

На странице Checkout предусмотрен резервный режим: если флаги выключены, но ключи провайдера заполнены, метод может отобразиться. На странице Order список методов формируется строго по флагам включения.

---

Логика оплаты ("Сначала деньги")

Система работает по принципу гарантированной оплаты перед выдачей:

1. Оформление заказа: Пользователь собирает корзину и переходит к оформлению.
2. Оплата:
   • Если выбран внешний шлюз (UnitPay, FreeKassa и др.), создается платеж на стороне провайдера.
   • Если выбрана оплата с баланса, средства списываются мгновенно (транзакционно).
3. Ожидание: Если ссылка на оплату не может быть сгенерирована мгновенно, пользователь перенаправляется на страницу заказа со статусом pending, где может повторить попытку или выбрать другой метод.
4. Безопасность: Все платежные шлюзы используют унифицированную проверку цифровой подписи (Signature/Hash). Это гарантирует, что уведомления об оплате (callbacks) приходят действительно от платежной системы, а не от злоумышленников.
5. Выдача: Только после получения подтверждения (статус paid) товары отправляются в очередь выдачи (Delivery Queue).

---

Инструкции по подключению

1. UnitPay

Популярная система для приема платежей (карты, СБП, крипта).

• Регистрация: UnitPay
• Настройки в RUSTCMS:
  • Public Key: Ваш PUBLIC KEY проекта (например, 444828-f674f). Находится в настройках формы оплаты.
  • Secret Key: Секретный ключ проекта (SECRET KEY).
  • Разрешенные методы: (Опционально) Коды методов через запятую, например cards,sbp. Оставьте пустым для всех методов.
• Важно:
  • Secret Key обязателен. Если ключ не задан, система не будет предлагать UnitPay в списке методов.
  • Скрипт поддерживает буквенно-цифровые ID проектов (например, 444828-f674f).
  • Система использует современный API UnitPay (2025) с поддержкой подписи через ksort.
  • Внимание: Для полноценной работы редиректов и оплаты необходимо верифицировать аккаунт документами. Без полной верификации страница оплаты может выдавать ошибку "Страница не найдена".
• Настройки в UnitPay (Личный кабинет):
  • Fail URL (Адрес при ошибке): https://ваш-сайт.ру/profile
  • Success URL (Адрес успешной оплаты): https://ваш-сайт.ру/profile
  • Redirect URL (если используется): https://ваш-сайт.ру/profile
  • Callback URL (Уведомления): https://ваш-сайт.ру/api/payments/unitpay/callback.php
    (Этот URL также должен быть прописан в config/local.php, установщик делает это автоматически)

2. FreeKassa

Агрегатор с большим количеством методов оплаты (карты, крипта, FKWallet).

• Регистрация: FreeKassa (freekassa.net)
• Важно для пользователей из РФ: Платежи через FreeKassa могут требовать включенного VPN. В профиле пользователя добавлено соответствующее уведомление и ссылка на рекомендуемый VPN (t.me/VlessVipBot).
• Настройки в RUSTCMS:
  • ID Магазина (Merchant ID): ID вашего магазина из личного кабинета.
  • Секретное слово 1 (Secret 1): Используется для создания формы оплаты (подписи).
  • Секретное слово 2 (Secret 2): Используется для проверки уведомлений об оплате (callback).
• Настройки в FreeKassa (раздел "Настройки"):
  • URL оповещения (Callback): https://ваш-сайт.ру/api/payments/freekassa/callback.php
  • Метод оповещения: POST
  • URL возврата (успех): https://ваш-сайт.ру/profile (Метод: GET)
  • URL возврата (неудача): https://ваш-сайт.ру/profile (Метод: GET)
• Важно:
  • Скрипт автоматически проверяет IP-адреса серверов FreeKassa для защиты от взлома.
  • Убедитесь, что правильно скопировали оба секретных ключа в соответствующие поля админки.

3. ENOT.io

Удобный агрегатор для приема платежей.

• Регистрация: ENOT.io
• Настройки в RUSTCMS:
  • Merchant ID: ID магазина (UUID).
  • Secret Key: Секретный ключ (Webhook Secret Key) для проверки подписи уведомлений.
  • API Key: API Ключ (x-api-key) для создания платежей.
• Настройки в ENOT.io:
  • Webhook URL: https://ваш-сайт.ру/api/payments/enot/callback.php
  • Выпустите API Ключ в настройках интеграции кассы.
  • Разрешите IP вашего сервера, если требуется.

4. ЮMoney (YooMoney)

Прием платежей на кошелек ЮMoney (для физлиц).

• Регистрация: ЮMoney
• Настройки в RUSTCMS:
  • Номер кошелька: Ваш номер счета (начинается на 41001...).
  • Secret Key: Секретное слово для HTTP-уведомлений (получаете на сайте ЮMoney).
• Настройки в ЮMoney:
  • В кошельке включите HTTP‑уведомления и укажите адрес для уведомлений.
  • Адрес уведомлений: https://ваш-сайт.ру/api/payments/yoomoney/callback.php
  • Сохраните секретное слово и вставьте его в поле Secret Key в админке.
  • Важно: Убедитесь, что галочка "Отправлять уведомление по HTTP" включена.
• Особенности интеграции:
  • Скрипт автоматически обрабатывает входящие уведомления и проверяет подпись (SHA-1).
  • Поддерживается гибкая проверка подписи (независимо от порядка параметров), что решает проблемы с изменениями API ЮMoney.
  • В случае проблем с зачислением, включите логирование сигнатуры в local.php (см. раздел Настройка).

5. Баланс пользователя

Встроенная система баланса является основным и единственным способом оплаты товаров.

• Отображение: Баланс отображается в шапке сайта (слева от корзины) и в меню пользователя.
• Пополнение:
  • Пользователь может пополнить баланс через страницу Профиля или автоматически при оформлении заказа, если средств не хватает.
  • Внешние шлюзы (UnitPay, FreeKassa и т.д.) используются исключительно для пополнения баланса.
  • Также возможно пополнение через Промокоды (тип Fixed), которые активируются в Профиле.
• Оплата товаров:
  • Оплата товаров возможна только при наличии достаточной суммы на балансе.
  • Кнопка оплаты становится активной только когда баланс пользователя покрывает стоимость корзины.
• Безопасность: Операции с балансом защищены транзакциями базы данных (ACID), что исключает двойные списания.

---

Проверка работы

1. После настройки создайте тестовый товар стоимостью 1-10 рублей.
2. Попробуйте купить его через внешний шлюз. Статус заказа должен измениться на paid.
3. Пополните баланс своего аккаунта через Профиль.
4. Попробуйте купить товар, выбрав "Списать с баланса". Заказ должен мгновенно получить статус paid, а товар — попасть в очередь выдачи.
5. Если статус не меняется, проверьте логи веб-сервера и файл /admin/logs.