Установка модуля 2328 Pay для 1C-Bitrix
========================================

Модуль работает со стандартным модулем «Интернет-магазин» (sale) и не
требует установки через Marketplace: это пользовательский обработчик
платежной системы (user payment handler), который просто копируется
в файловую структуру сайта.

Поддерживаются «Битрикс: Управление сайтом» редакции «Малый бизнес»,
«Бизнес» и «1C-Bitrix24 в коробке» — везде, где есть модуль sale.

Структура архива:
-----------------
  bitrix/php_interface/include/sale_payment/pay2328/
    .description.php                -- описание полей в админке
    payment.php                     -- шаблон оплаты (редирект на 2328 Pay)
    lang/ru/.description.php
    lang/ru/payment.php
    lang/en/.description.php
    lang/en/payment.php

  pay2328_callback.php              -- обработчик webhook (корень сайта)

Имена файлов .description.php и payment.php обязательны — их
ожидает Bitrix\Sale\PaySystem\CompatibilityHandler при включении
пользовательского обработчика.

Шаг 1. Загрузите файлы на сервер
---------------------------------
Скопируйте содержимое папки pay2328/ в корень сайта, сохраняя структуру:

  <DOCUMENT_ROOT>/bitrix/php_interface/include/sale_payment/pay2328/
  <DOCUMENT_ROOT>/pay2328_callback.php

Через FTP/SFTP — просто перетащите содержимое pay2328/ в корень сайта.

Через SSH:
  scp -r pay2328/bitrix root@IP:/путь/до/bitrix/корня/
  scp pay2328/pay2328_callback.php root@IP:/путь/до/bitrix/корня/

Проверьте права доступа (должны быть читаемы веб-сервером):
  chown -R bitrix:bitrix /путь/до/bitrix/bitrix/php_interface/include/sale_payment/pay2328
  chmod 644 /путь/до/bitrix/pay2328_callback.php

Шаг 2. Зарегистрируйте платёжную систему в админке
---------------------------------------------------
1. Войдите в админку: https://ВАШ_ДОМЕН/bitrix/admin/
2. Магазин → Настройки → Платёжные системы
3. Нажмите «Добавить платёжную систему»
4. На вкладке «Платёжная система»:
   - Название: 2328 Pay
   - Активность: Да
   - Сортировка: 100
   - Плательщик: отметьте нужные типы плательщиков
   - Обработчик ПС: выберите «2328 Pay» (пользовательский)
     * Если в списке нет — проверьте, что файлы на месте и путь
       /bitrix/php_interface/include/sale_payment/pay2328/ создан.
5. Нажмите «Сохранить».
6. Затем откройте созданную ПС → вкладка «Пользовательские настройки».
   Для каждого типа плательщика заполните только реквизиты и URL:
   - UUID проекта        — из личного кабинета 2328.io
   - API ключ            — из личного кабинета 2328.io
   - URL API             — https://api.2328.io/api (по умолчанию)
   - URL callback        — /pay2328_callback.php
   - URL возврата        — /personal/order/ (или другая ваша страница)
   - URL успешной оплаты — /personal/order/payment/

   Идентификатор заказа, сумма и валюта не настраиваются вручную —
   модуль читает их напрямую из заказа (~ID / ~SHOULD_PAY / ~CURRENCY).
7. Сохраните.

Шаг 3. Привяжите к способу оплаты
----------------------------------
Магазин → Настройки → Службы → Доставки/Оплаты, либо в настройках
типа плательщика убедитесь, что новая ПС доступна для покупателя
в checkout-е.

Шаг 4. Настройте callback URL в 2328 Pay
-----------------------------------------
URL callback задаётся на стороне 2328 Pay автоматически при создании
счёта (передаётся параметром url_callback). Дополнительная настройка
в личном кабинете 2328.io не требуется.

Убедитесь, что https://ВАШ_ДОМЕН/pay2328_callback.php доступен
извне (не закрыт basic-auth, .htaccess, IP-фильтрами и т.п.).

Шаг 5. Тестирование
--------------------
1. Создайте тестовый заказ в витрине.
2. На шаге оплаты выберите «2328 Pay».
3. Должен произойти редирект на хостинг-чекаут 2328 Pay.
4. Оплатите (в testnet-е или малой суммой).
5. Проверьте в админке Битрикс:
   - заказ должен перейти в статус «Оплачен»
   - в «Настройки → Инструменты → Журнал событий» должны появиться
     записи PAY2328_WEBHOOK с uuid/order_id/status


ОТЛАДКА
--------
Все ошибки пишутся в журнал событий Битрикс:
  Настройки → Инструменты → Журнал событий

Типы событий этого модуля:
  PAY2328_API_ERROR         — ошибка при создании счёта
  PAY2328_WEBHOOK           — пришёл callback от 2328 Pay
  PAY2328_INVALID_SIGNATURE — callback с невалидной подписью
  PAY2328_AMOUNT_MISMATCH   — в callback-е сумма меньше заказа
  PAY2328_UNKNOWN_STATUS    — неизвестный payment_status


УДАЛЕНИЕ
---------
1. В админке: Магазин → Настройки → Платёжные системы →
   найдите 2328 Pay → «Удалить».
2. Удалите файлы:
   rm -rf <DOCUMENT_ROOT>/bitrix/php_interface/include/sale_payment/pay2328
   rm <DOCUMENT_ROOT>/pay2328_callback.php


ЧАСТО ЗАДАВАЕМЫЕ ВОПРОСЫ
-------------------------

Q: В списке «Обработчик ПС» не видно 2328 Pay.
A: Проверьте, что файл .description.php лежит точно по пути
   /bitrix/php_interface/include/sale_payment/pay2328/.description.php
   (имя начинается с точки — это обязательное требование Bitrix).
   Очистите кеш: Настройки → Настройки продукта → Автокеширование →
   «Очистить файл кеша».

Q: После оплаты заказ не переходит в «Оплачен».
A: Откройте Журнал событий. Если есть PAY2328_INVALID_SIGNATURE —
   API-ключ в настройках ПС не совпадает с ключом проекта в 2328.io.
   Если записей нет вообще — callback URL недоступен извне
   (проверьте curl -X POST https://ВАШ_ДОМЕН/pay2328_callback.php).

Q: Модуль работает с редакцией «Старт»?
A: Нет. Требуется модуль «Интернет-магазин» (sale) — редакции
   «Малый бизнес», «Бизнес» или выше.
