170 lines
30 KiB
Markdown
170 lines
30 KiB
Markdown
# 🌟 Платёжный модуль «Монета» для [PHPShop](https://www.phpshop.ru/)
|
||
|
||
|
||
|
||
|
||
|
||
> **© Правообладатель:** НКО «МОНЕТА» (ООО)
|
||
|
||
> **📦 Версия модуля: 2.0**
|
||
|
||
> ℹ️ Модуль заменяет встроенный в PHPShop 6.7 и 7.0 модуль «Монета» 1.0: тот же каталог `moneta` и тот же способ оплаты, настройки переносятся кнопкой «Обновить модуль» (раздел [«Обновление со встроенного модуля»](#обновление-со-встроенного-модуля)).
|
||
|
||
> **ℹ️ Требования:**<br>
|
||
> **PHPShop:** 6.7.0+<br>
|
||
> **PHP:** 7.4+<br>
|
||
> **Валюта магазина:** только RUB<br>
|
||
|
||
## 🚀 Установка и настройка модуля
|
||
|
||
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` и знак рубля темы (`<span class=rubznak>p</span>`) |
|
||
| `@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/)
|
||
|
||
---
|
||
|
||
**✅ Модуль настроен, приятных платежей!** 💰🎉
|