# 🌟 Платёжный модуль PayAnyWay для [OpenCart](https://www.opencart.com/) v4.x
> **📦 Версия модуля: 1.0.4**
> **ℹ️ Совместимость версий OpenCart:**
> 4.0.2.0, 4.0.2.1, 4.0.2.2, 4.0.2.3, 4.1.0.0, 4.1.0.1, 4.1.0.2, 4.1.0.3, 4.1.0.4
> **ℹ️ Совместимость версий OpenCart "Русская сборка":**
> 4.0.2.1, 4.0.2.2, 4.0.2.3, 4.1.0.0, 4.1.0.4
> **ℹ️ Примечание по валюте**
> Данный модуль работает **только с валютой RUB (Российский рубль)**.
> Перед активацией модуля убедитесь, что на сайте в качестве базовой валюты установлен RUB, либо у пользователя выбран счёт в RUB. Использование других валют не поддерживается.
## 🏗️ Структура модуля
```
├── admin
│ ├── controller/payment/payanyway.php
│ ├── language/{en-gb,ru-ru}/payment/payanyway.php
│ ├── view/image/payment/payanyway.png
│ └── view/template/payment/payanyway.twig
├── catalog
│ ├── controller/payment/
│ │ ├── callback.php — Check URL и Pay URL
│ │ └── payanyway.php — форма оплаты, возврат покупателя
│ ├── controller/startup/payanyway.php — приём Check/Pay URL методом POST, сброс оплаченного заказа из сессии
│ ├── language/{en-gb,ru-ru}/payment/payanyway.php
│ ├── library/payanyway/traits/payanyway.php
│ ├── model/payment/payanyway.php — блокировка заказа
│ └── view/template/payment/payanyway.twig
├── install.json
└── README.md
```
## 🚀 Установка и настройка модуля
1. 📥 [Скачайте архив модуля](https://git.pub.moneta.ru/CMS/openCart4/releases) и переименуйте в `payanyway.ocmod.zip`.
2. 📂 Загрузите расширение через панель управления интернет-магазином.
В разделе **"Модули / Расширения"** выберите подраздел **"Установка расширений"**. Нажмите **"Загрузить"** и выберите скачанный архив `payanyway.ocmod.zip`.
В списке установленных расширений найдите **PayAnyWay** и нажмите **"Установить"**.
3. ⚙️ В подразделе **"Модули / Расширения"** выберите тип расширения **"Оплата"**.
В списке способов оплаты найдите **PayAnyWay** и нажмите:
- **«Установить»** — для установки модуля
- **«Редактировать»** — для перехода к настройкам
4. ✏️ Заполните соответствующие поля в настройках способа оплаты:
| Поле | Описание |
|-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Статус** | Включите или выключите модуль оплаты |
| **Номер счёта** | Ваш номер расширенного счёта в системе [MONETA.RU](https://moneta.ru/), только цифры |
| **Код проверки целостности данных** | Код проверки целостности данных, указанный в настройках расширенного счёта в системе [MONETA.RU](https://moneta.ru/). Сохранённый код в форме не показывается: оставьте поле пустым, чтобы не менять его |
| **Сервер платежей** | `Боевой` / `Демо` (демо-площадка MONETA.RU) |
| **Тестовый режим** | Имитация оплаты без реального списания средств. Должен совпадать с настройкой счёта в MONETA.RU |
| **Фискализация чеков** | Включайте, только если к счёту подключён кассовый сервис [kassa.payanyway.ru](https://kassa.payanyway.ru/) |
| **Email для чеков** | Обязателен при фискализации. Подставляется в чек, только если у покупателя нет ни e-mail, ни телефона (ФИО покупателя в чеке остаётся) |
| **НДС** | Ставка НДС всех позиций чека |
| **Признак способа расчёта** | Для товаров, доставки и сборов. Обычно `Полный расчёт`. Проданные подарочные сертификаты всегда идут авансом |
| **Признак предмета расчёта** | Для товаров. Доставка и сборы всегда идут услугой, подарочные сертификаты — платежом |
| **Валюта платежа** | `RUB` |
| **Статусы заказа** | Выберите соответствующие статусы заказа из списка |
| **Обрабатываемый** | Укажите статус заказа, который выставляется при его создании |
| **Успешный** | Укажите статус заказа, который выставляется при успешной оплате |
| **Неуспешный** | Укажите статус заказа, который выставляется при ошибке оплаты |
| **Отменённые** | Заказ в этих статусах не оплачивается: на проверочный запрос и уведомление об оплате модуль отвечает отказом (деньги за такую оплату возвращаются в личном кабинете MONETA.RU, номер операции — в журнале ошибок). Статусы Обрабатываемого, Успешного и Неуспешного заказа выбрать нельзя. По умолчанию `Canceled`, `Canceled Reversal`, `Voided` |
| **URL для уведомлений** | Адрес Check URL и Pay URL для настроек счёта MONETA.RU, кнопка «Скопировать» |
| **Регион отображения** | Географическая зона, в которой будет отображаться способ оплаты |
| **Порядок сортировки** | Определяет порядок отображения платежного метода в списке методов оплаты при оформлении заказа. Чем меньше число, тем выше позиция в списке |
Сумма позиций чека всегда равна сумме оплаты: налоги OpenCart входят в цену товаров, скидки (купоны, подарочные сертификаты, бонусные баллы) распределяются по товарам, доставка и сборы идут отдельными позициями.
> ℹ️ Сумма платёжной формы записывается в номер транзакции (`MNT_TRANSACTION_ID`, например `42_1500000_20261022120000UTC`; время — UTC). Если после показа формы сумма заказа изменилась, оплата по старой форме отклоняется: покупателю нужно заново открыть оплату заказа.
> ⚠️ **После обновления модуля** откройте настройки PayAnyWay, проверьте новые поля (фискализация после обновления включена) и нажмите **«Сохранить»**. Пока при включённой фискализации не задан «Email для чеков», над формой настроек показывается предупреждение.
## 🔄 Обновление модуля
OpenCart 4 не устанавливает расширение поверх уже установленного: загрузка нового архива в **«Установка расширений»** заканчивается ошибкой «Расширение уже установлено» (Extension already installed) или «Файл уже существует» (File already exist), а установка — ошибкой «Путь payanyway/ уже существует» (Path payanyway/ already exists). Обновить модуль можно одним из двух способов.
### Способ 1. Замена файлов — настройки сохраняются (рекомендуется)
Нужен доступ к файлам сайта (FTP, SSH или файловый менеджер хостинга).
1. Распакуйте архив новой версии.
2. Скопируйте из него `admin/`, `catalog/`, `install.json` и `README.md` в каталог `extension/payanyway/` в корне OpenCart с заменой файлов.
3. Откройте настройки PayAnyWay (**«Модули / Расширения» → «Оплата» → PayAnyWay → «Редактировать»**), проверьте новые поля и нажмите **«Сохранить»**.
В списке **«Установка расширений»** останется прежний номер версии — на работу модуля это не влияет.
### Способ 2. Переустановка через панель управления — настройки удаляются
При удалении способа оплаты OpenCart стирает все настройки модуля. Заранее перепишите их; код проверки целостности в форме не показывается — возьмите его в настройках расширенного счёта в личном кабинете MONETA.RU.
1. **«Модули / Расширения» → «Оплата»** → PayAnyWay → **«Деинсталлировать»** (Uninstall).
2. **«Модули / Расширения» → «Установка расширений»** → PayAnyWay → **«Деинсталлировать»** (Uninstall, удаляет файлы модуля), затем **«Удалить»** (Delete, кнопка с корзиной — удаляет архив и строку из списка).
3. Загрузите архив новой версии, переименованный в `payanyway.ocmod.zip`, и нажмите **«Установить»**.
4. **«Модули / Расширения» → «Оплата»** → PayAnyWay → **«Установить»**, затем **«Редактировать»**: заполните настройки и нажмите **«Сохранить»**.
> ⚠️ Если на шаге 3 появляется «Путь payanyway/ уже существует», файлы прежней версии остались на сервере (например, строку удалили корзиной, не нажав перед этим «Деинсталлировать»). Удалите каталог `extension/payanyway/` через FTP или файловый менеджер и снова нажмите **«Установить»**.
---
## 🔧 Инструкция по настройке счета PayAnyWay
1. 📝 [Зарегистрируйтесь](https://payanyway.ru/partnerRegistration.htm) в платёжной системе PayAnyWay и заполните все необходимые данные. Дождитесь проверки аккаунта и создайте **расширенный счет**.
2. ⚙️ Заполните настройки расширенного счета (раздел **«Мой счет» → «Управление счетами» → «Редактировать счет»**):
| Параметр | Значение |
|------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Тестовый режим** | `Нет` |
| **Check URL** | `https://your_site_name/index.php?route=extension/payanyway/payment/callback` |
| **Pay URL** | `https://your_site_name/index.php?route=extension/payanyway/payment/callback` |
| **HTTP method\*** | `GET` или `POST` (требуется настройка) |
| **Можно переопределять настройки в URL** | `Да` |
| **Подпись формы оплаты обязательна** | `Да` |
| **Код проверки целостности данных** | `ваш_код` (произвольный набор символов) |
| **Success URL** | Оставить пустым |
| **Fail URL** | Оставить пустым |
| **InProgress URL** | Необязательное поле. URL страницы магазина, куда должен попасть покупатель после успешного запроса на авторизацию средств, до подтверждения списания и зачисления средств. Поддерживается ограниченным количеством методов оплаты. Переход пользователя произойдет независимо от получения магазином средств и отчета о проведенной оплате |
| **Return URL** | Оставить пустым |
> ⚠️ **Важно!** Для кириллического домена PayURL и CheckURL должны быть указаны в кодировке [Punycode](https://2ip.ru/punycode/).
### \* 📨 Уведомления методом POST
При **HTTP method** = `POST` MONETA.RU переносит параметры из адреса Check URL / Pay URL в тело запроса, в том числе `route=extension/payanyway/payment/callback`. Штатный OpenCart 4 ищет маршрут только в адресе и без доработки отвечает главной страницей, а платёжная форма показывает «Код ошибки: 302».
Модуль решает это собственным startup-контроллером витрины `payanyway_post_route`: маршрут колбэка (и только его) берётся из тела запроса. Ядро OpenCart не изменяется, модификации обновлять не нужно.
1. Startup регистрируется автоматически при установке способа оплаты PayAnyWay (**«Модули / Расширения» → «Оплата» → «Установить»**).
2. Если модуль обновлён поверх старой версии без переустановки, откройте настройки PayAnyWay и нажмите **«Сохранить»**: startup зарегистрируется при сохранении.
3. Если startup не зарегистрирован или выключен, над формой настроек будет жёлтое предупреждение. Проверить вручную можно в **«Модули / Расширения» → «Startup»** (Extensions → Startup): строка `payanyway_post_route` должна быть включена.
Если включить startup не удаётся, выберите в настройках счёта **HTTP method** = `GET`: при GET уведомления доходят и без него. Но startup нужен и для оформления следующего заказа (см. ниже про `SameSite`), поэтому лучше держать его включённым.
> ⚠️ **Важно!** Если после возврата с сайта MONETA.RU покупатель оказывается разлогинен, дело в атрибуте `SameSite` cookie сессии. В OpenCart 4 по умолчанию стоит `Strict`: с ним браузер не отправляет cookie, когда покупатель переходит на магазин с другого сайта, и OpenCart открывает новую пустую сессию. Старая сессия при этом сохраняет оплаченный заказ: без startup `payanyway_post_route` следующий заказ в том же браузере не создаётся, и платёжная форма открывает уже оплаченный. Startup снимает оплаченный или отменённый заказ из сессии на странице оформления, и OpenCart заводит новый.
> 1. Откройте **«Система» → «Настройки»** (System → Settings) и отредактируйте магазин.
> 2. На вкладке **«Сервер»** (Server) в поле **«Сессионный файл Cookie»** (Session Samesite Cookie) выберите `Lax` и сохраните.
>
> `Lax` достаточно: покупатель возвращается с MONETA.RU обычным переходом по ссылке, и cookie при таком переходе отправляется, а в остальных запросах с чужих сайтов — нет, поэтому защита от подделки запросов (CSRF) сохраняется. Значение `None` не выбирайте: cookie будет уходить при любых запросах с чужих сайтов, а браузеры принимают `SameSite=None` только для сайтов на HTTPS.
---
## 📚 Полезные ресурсы OpenCart
* [OpenCart](https://www.opencart.com/)
* [Документация](https://docs.opencart.com/)
* [Релизы](https://github.com/opencart/opencart/releases)
## 📚 Полезные ресурсы OpenCart "Русская сборка"
* [Русская сборка OpenCart](https://opencart-russia.ru/)
* [Документация и FAQ](https://forum.opencart-russia.ru/forums/wiki/)
* [Форум поддержки](https://forum.opencart-russia.ru/)
---
**✅ Модуль настроен, приятных платежей!** 💰🎉