# 🌟 Платёжный модуль «Монета» для [PHPShop](https://www.phpshop.ru/)
> **© Правообладатель:** НКО «МОНЕТА» (ООО)
> **📦 Версия модуля: 2.0**
> ℹ️ Модуль заменяет встроенный в PHPShop 6.7 и 7.0 модуль «Монета» 1.0: тот же каталог `moneta` и тот же способ оплаты, настройки переносятся кнопкой «Обновить модуль» (раздел [«Обновление со встроенного модуля»](#обновление-со-встроенного-модуля)).
> **ℹ️ Требования:**
> **PHPShop:** 6.7.0+
> **PHP:** 7.4+
> **Валюта магазина:** только RUB
## 🚀 Установка и настройка модуля
1. 📥 [Скачайте архив модуля](https://git.pub.moneta.ru/CMS/PHPShop/releases).
2. Распакуйте архив в каталог `phpshop/modules/` магазина — в корне архива лежит каталог `moneta`, он заменит файлы встроенного модуля «Монета». Загрузить архив через админку PHPShop нельзя: в ней нет установки модулей из архива. Два способа:
- **файловый менеджер панели хостинга** (ISPmanager, cPanel, Plesk и др.): загрузите архив в `phpshop/modules/` и распакуйте его там, соглашаясь на замену файлов, затем удалите архив и распакованный рядом `README.md` (это эта инструкция, модулю он не нужен);
- **FTP/SFTP**: распакуйте архив на своём компьютере и скопируйте каталог `moneta` в `phpshop/modules/` с заменой файлов.
В итоге должен получиться путь `phpshop/modules/moneta/install/module.xml` — без лишнего вложенного каталога. Если встроенный модуль «Монета» у вас включён, сначала прочитайте раздел [«Обновление со встроенного модуля»](#обновление-со-встроенного-модуля).
3. Админка PHPShop -> **«Модули»** -> **«Монета»** -> **«Включить»**.
4. Откройте настройки модуля и заполните поля (таблица ниже), нажмите **«Применить»**.
5. Включите способ оплаты **«Приём платежей банковскими картами, через СБП и Pay-сервисы (Монета)»**: **«Заказы»** -> **«Способы оплаты»** (`/phpshop/admpanel/admin.php?path=payment`). При установке он встаёт первым в списке способов оплаты при оформлении заказа; порядок меняется полем **«Приоритет»** в карточке способа оплаты (меньшее число — выше).
6. Настройте счёт в личном кабинете MONETA.RU (раздел ниже).
> **Выключение модуля в PHPShop удаляет его таблицы** — настройки придётся ввести заново.
### Магазин с базой в UTF-8
Если в `phpshop/inc/config.ini` указано `charset = "utf8"`, переключите кодировку статических файлов в `.htaccess` в корне сайта — PHPShop поставляет его с кодировкой windows-1251, а строка для UTF-8 в нём уже есть, но закомментирована:
```apache
#AddDefaultCharset windows-1251
AddDefaultCharset utf-8
```
Без этого браузер читает файлы локали PHPShop (`phpshop/locale/russian_utf/*.js`) в неверной кодировке: подсказки и сообщения админки и витрины (например, «Пожалуйста, выберите доставку») выводятся кракозябрами. На nginx то же самое задаёт директива `charset utf-8;` в блоке `server` сайта. После изменения обновите страницы с очисткой кэша браузера (Ctrl+F5). Модуль от этой настройки не зависит: его страницы и данные для MONETA.RU выводятся в нужной кодировке сами.
## Обновление со встроенного модуля
В PHPShop 6.7 и 7.0 модуль «Монета» 1.0 уже встроен — в том же каталоге `phpshop/modules/moneta`. Если он у вас включён, не выключайте его: при выключении PHPShop удаляет таблицы модуля, и номер счёта с кодом пришлось бы вводить заново. Обновление переносит настройки само.
**Перед обновлением**
- Обновляйте, когда нет оплат «в процессе»: оплату, которую покупатель начал во встроенном модуле, а MONETA.RU подтвердила уже после обновления, новый модуль не узнает и не зачтёт — такие заказы после обновления сверьте с операциями в личном кабинете MONETA.RU и отметьте оплаченными вручную.
- Если вы правили шаблоны в каталоге модуля (`templates/`), сохраните их копию — файлы будут заменены.
**Обновление**
1. Распакуйте архив модуля в `phpshop/modules/` с заменой файлов встроенного модуля — как в шаге 2 [установки](#-установка-и-настройка-модуля). Модуль не выключайте.
2. Админка PHPShop -> **«Модули»** -> **«Монета»**. На вкладке «Основное» появится предупреждение, что настройки ещё от встроенного модуля, — до нажатия кнопки из шага 3 приём оплат выключен (покупатель видит «Оплата через Монету временно недоступна»), а изменения на этой вкладке не сохраняются.
3. Вкладка **«О модуле»**: PHPShop пишет «Версия ядра 2.0 не соответствует версии базы данных 1.2» — нажмите **«Обновить модуль»**.
4. Проверьте настройки на вкладке «Основное» и нажмите **«Применить»**:
- **Номер счёта** перенесён из поля «ID» встроенного модуля (только цифры), **код проверки целостности данных** — из поля «Секретное слово», **«Оплата при статусе»** и **«Описание оплаты»** — как было;
- **Сервер платежей** — «Боевой», как работал встроенный модуль; для демо-счёта выберите «Демо»;
- **Тестовый режим** и **фискализация** — выключены: включите их, если они нужны (см. [«Настройки модуля»](#настройки-модуля)).
5. Способ оплаты остаётся прежним, включённым или выключенным, как был. Его название и иконка заменяются на новые, если вы их не меняли; изменённые сохраняются.
**Личный кабинет MONETA.RU** — настройки счёта (раздел [«Настройка счёта в личном кабинете MONETA.RU»](#настройка-счёта-в-личном-кабинете-monetaru)):
| Поле | Было у встроенного модуля | Что указать |
|-------------------------------|----------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Check URL** | пусто | `https://<ваш-сайт>/phpshop/modules/moneta/payment/callback.php` — модуль проверит заказ до оплаты: сумму, статус, не оплачен ли он уже |
| **Pay URL** | `https://<ваш-сайт>/phpshop/modules/moneta/payment/result.php` | `…/payment/callback.php`, как Check URL. Старый адрес `result.php` тоже работает, менять его можно не сразу |
| **Success URL**, **Fail URL** | `http://<ваш-сайт>/success` и `/fail` | Лучше включить флаг **«Можно переопределять настройки в URL»**: модуль сам вернёт покупателя на страницу со статусом оплаты. Без флага укажите адреса **со слэшем на конце** — `https://<ваш-сайт>/success/` и `https://<ваш-сайт>/fail/`: адреса без слэша PHPShop не открывает (404), так было и со встроенным модулем |
## Настройки модуля
| Поле | Описание |
|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Номер счёта** | Номер расширенного счёта [MONETA.RU](https://moneta.ru/), только цифры |
| **Код проверки целостности данных** | Код проверки целостности данных, указанный в настройках расширенного счёта. Сохранённый код в настройках не показывается — оставьте поле пустым, чтобы его не менять |
| **Сервер платежей** | `Боевой` (по умолчанию) / `Демо` (demo.moneta.ru, отдельный номер счёта) |
| **Тестовый режим** | По умолчанию `Выкл`. Передаёт `MNT_TEST_MODE=1`; должен совпадать с флагом «Тестовый режим» в настройках счёта |
| **URL для уведомлений** | Скопируйте и укажите этот адрес в настройках расширенного счёта как Check URL и Pay URL |
| **Описание оплаты** | Текст над суммой и кнопкой оплаты на странице «Заказ оформлен» и в личном кабинете покупателя. По умолчанию `Оплатите пожалуйста свой заказ`, пусто — без текста. Пока заказ ждёт проверки менеджером, текст не показывается: покупатель видит «Заказ обрабатывается менеджером.» |
| **Фискализация чеков** | По умолчанию `Выкл`. Фискализация чеков по 54-ФЗ средствами системы MONETA.RU сервисом kassa.payanyway.ru |
| **Email для чеков** | Обязателен при включённой фискализации: если у покупателя нет ни email, ни телефона, чек уйдёт на этот адрес |
| **Система налогообложения** | По умолчанию `Не передавать` — касса возьмёт её из своих настроек |
| **НДС на товары** | `Из настроек раздела «Настройка цен»` (по умолчанию) — «Значение НДС» в разделе «Настройка цен» системных настроек PHPShop; иначе одна ставка на все товары, включая расчётные 5/105 … 22/122 |
| **НДС на доставку** | `Из настроек способа доставки` (по умолчанию) — «Значение НДС» способа доставки; иначе одна ставка на доставку |
| **Признак способа расчёта** | У всех позиций чека, включая доставку. По умолчанию `Полный расчёт` |
| **Признак предмета расчёта** | У товаров. По умолчанию `Товар`; для услуг, работ и др. — по перечню кассы. Доставка в чеке всегда «Услуга» |
| **Оплата при статусе** | `Новый заказ` — оплата сразу после оформления; другой статус — после проверки заказа менеджером |
| **Статус после оплаты** | По умолчанию `Оплачено платежными системами` |
Сохранять настройки может только администратор с правом «Модули: редактирование» (раздел «Администраторы», вкладка «Права»). Модуль принимает сохранение только со страницы настроек этого же магазина. Если вместо сохранения появилось «запрос пришёл не со страницы этого магазина», откройте настройки заново и нажмите «Применить». Если сообщение повторяется, проверьте, не убирает ли браузер, расширение или прокси заголовки Origin и Referer.
## Оформление блока оплаты
На странице «Заказ оформлен» покупатель видит карточку оплаты: логотип MONETA.RU, описание оплаты из настроек, сумму «К оплате», кнопку «Оплатить <сумма>» и пояснение о переходе на защищённую страницу MONETA.RU. Карточка собирается по шаблону `phpshop/modules/moneta/templates/payment_forma.tpl`, стили — `templates/moneta.css`, логотип — `templates/moneta.svg`; их можно изменить под тему магазина:
| Переменная | Что подставляется |
|-----------------------|---------------------------------------------------------------------------------------------------|
| `@payment_info@` | «Описание оплаты» из настроек модуля — обычный текст, переносы строк сохраняются |
| `@payment_info_hide@` | `moneta-hide`, если описание пустое или заказ сейчас нельзя оплатить |
| `@moneta_total@` | Сумма к оплате, как её пишет витрина: `18 500` и знак рубля темы (`p`) |
| `@moneta_total_hide@` | `moneta-hide`, если заказ сейчас нельзя оплатить, — скрывает сумму и пояснение |
| `@payment_forma@` | Форма с кнопкой «Оплатить» или текст о состоянии заказа |
Переменные `@payment_info@` и `@payment_forma@` — те же, что во встроенном модуле PHPShop, поэтому шаблон от него подойдёт. Пути к файлам модуля в шаблоне пишутся без начального слэша (`phpshop/modules/...`) — витрина PHPShop сама делает их абсолютными. Шаблон и стили лежат в каталоге модуля: **обновление модуля их перезапишет** — сохраните свою версию перед обновлением.
## 🔧 Настройка счёта в личном кабинете MONETA.RU
1. 📝 [Зарегистрируйтесь](https://payanyway.ru/partnerRegistration.htm) в платёжной системе PayAnyWay и заполните все
необходимые данные. Дождитесь проверки аккаунта и создайте **расширенный счет**.
2. ⚙️ Заполните настройки расширенного счета (раздел **«Мой счет» → «Управление счетами» → «Редактировать счет» →
«Показать дополнительные поля»**):
| Параметр | Значение |
|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Псевдоним** | любой, например `Монета` |
| **Тестовый режим** | `Нет` (как в настройке модуля) |
| **Check URL** и **Pay URL** | `https://<ваш-сайт>/phpshop/modules/moneta/payment/callback.php` — готовый адрес — в поле «URL для уведомлений» настроек модуля (кнопка «Копировать») и на вкладке «Инструкция» |
| **HTTP метод (PayUrl, CheckUrl)** | `POST` или `GET` |
| **Код проверки целостности данных** | произвольный набор символов; тот же код укажите в настройках модуля |
| **Подпись формы оплаты обязательна** | `Да` |
| **Можно переопределять настройки в url** | `Да` |
| **Success URL** | Оставить пустым |
| **Fail URL** | Оставить пустым |
| **InProgress URL** | Оставить пустым |
| **Return URL** | Оставить пустым |
> ⚠️ **Важно!** Для кириллического домена PayURL и CheckURL должны быть указаны в
> кодировке [Punycode](https://2ip.ru/punycode/).
3. Для фискализации чеков по 54-ФЗ средствами за рамками PHPShop настройте вашу кассу в сервисе kassa.payanyway.ru,
в настройках расширенного счёта в MONETA.RU установите Pay URL https://kassa.payanyway.ru/index.php?do=invoicepayurl,
а в настройках кассы пропишите Pay URL вашего интернет-магазина `https://<ваш-сайт>/phpshop/modules/moneta/payment/callback.php`.
В этом случае чек по 54-ФЗ будет пробиваться через kassa.payanyway.ru, а запрос на Pay URL магазина будет проходить через этот сервис транзитом.
## Журнал операций
**«Модули»** -> **«Монета»** -> **«Журнал операций»**: каждое уведомление MONETA.RU (проверка заказа и оплата) с ответом модуля. Код проверки целостности и подписи в журнал не пишутся.
На странице — 500 последних записей, по ним работают поиск и сортировка таблицы. Записи одного заказа за всё время находит поле над таблицей: введите номер заказа (`33-57`) или целиком `MNT_TRANSACTION_ID` из личного кабинета MONETA.RU.
На что обратить внимание:
- **«Вторая оплата оплаченного заказа»** — покупатель оплатил заказ дважды. Модуль вторую оплату не зачитывает, MONETA.RU будет повторять уведомление; сделайте возврат в личном кабинете MONETA.RU или свяжитесь с покупателем.
- **«Сумма не совпадает с заказом»**, **«У заказа другой способ оплаты»** — заказ изменили после того, как покупатель открыл форму оплаты. Верните сумму или способ оплаты — повторное уведомление MONETA.RU зачтёт оплату.
- **«Чек не собран»** — при включённой фискализации модуль не смог собрать чек заказа, и оплата не началась: без чека касса не пробьёт его по 54-ФЗ. Причина — в журнале ошибок PHP (строки с префиксом `moneta:`); обычно это сумма заказа выше предела кассы (42 949 672,95 ₽) или сбой базы данных.
- **«Тестовый режим не совпадает с настройкой модуля»** — флаг «Тестовый режим» в модуле и в настройках счёта MONETA.RU должен совпадать.
## Как проходит оплата
1. После оформления заказа (или в личном кабинете, если оплата доступна после проверки менеджером) покупатель нажимает кнопку оплаты и переходит на платёжную форму MONETA.RU.
2. MONETA.RU проверяет заказ (Check URL) и после оплаты уведомляет магазин (Pay URL) — модуль переводит заказ в статус «после оплаты».
3. Покупатель возвращается в магазин на страницу `/moneta/`. Если MONETA.RU уже подтвердила оплату — «Оплата прошла успешно»; если подтверждение ещё в пути — страница около минуты ждёт его и обновляется сама. Статус заказа виден только его владельцу: вошедшему покупателю или в том же браузере, где показывалась кнопка оплаты; остальным — «Заказ не найден». Статус заказа меняет только уведомление MONETA.RU, а не возврат покупателя. Шаблон страницы — `templates/return_forma.tpl`, стили — `templates/moneta.css`.
## 📚 Полезные ресурсы
* [PHPShop](https://www.phpshop.ru/)
* [PHP API](https://wiki.phpshop.ru/api/php-api)
* [HTML Верстальщику](https://wiki.phpshop.ru/dizain/verstalshiku)
* [Прайс-листы поставщиков в CSV](https://wiki.phpshop.ru/rabota-s-bazoi/import-i-eksport/csv)
* [Ручное добавление каталогов, товаров](https://wiki.phpshop.ru/tovary/ruchnoe-dobavlenie-tovarov)
* [Установка на хостинг](https://wiki.phpshop.ru/ustanovka-i-obnovlenie/ustanovka-na-khosting#ustanovka-cherez-arhiv-v-ruchnom-rezhime)
* [Разработчикам](https://wiki.phpshop.ru/moduli/razrabotchikam/)
---
**✅ Модуль настроен, приятных платежей!** 💰🎉