VibeFox Montonio for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

PHP: 8.0 или новее.

Валюта: валюта оформления заказа должна быть EUR или PLN. Для любой другой валюты способ оплаты не отображается при оформлении заказа.

Учётная запись Montonio: нужны ключ доступа (access key) и секретный ключ (secret key) вашего магазина из Montonio Partner System. Ключи для песочницы (sandbox) и для рабочего режима различаются, поэтому для каждой среды, которую вы используете, нужна своя пара. Больше ничего в Montonio настраивать не нужно: адрес для уведомлений передаётся с каждым платежом.

Публичный сайт: чтобы получать уведомления от Montonio, ваш магазин должен быть доступен из интернета. В противном случае заказы всё равно получат свой статус, когда покупатель вернётся в магазин.

Лицензионный ключ VibeFox: приобретается на vibefox.net. Один ключ работает на одном домене.

Установка

Скачиваемый файл — это один zip-архив с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_montonio_payment-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_montonio_payment.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаков для обеих версий.

OpenCart 3

1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_montonio_payment-oc3-(version).ocmod.zip. Расширение не содержит модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload этого пакета в корневую папку вашего магазина.

2. Перейдите в Extensions > Extensions, выберите тип Payments. Найдите VibeFox Montonio Payment и нажмите Install (зелёная кнопка +). Вашему пользователю администратора нужно право на изменение списка платёжных расширений.

3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек. Вставьте лицензионный ключ VibeFox в поле License key в блоке лицензии в верхней части страницы и нажмите Activate (см. Лицензионный ключ).

4. В Montonio Partner System откройте Stores > your store > API keys и скопируйте ключ доступа и секретный ключ для песочницы. Вставьте их в настройки и оставьте включённым Sandbox mode.

5. Включите Enable/Disable, нажмите Save и проверьте платёж в песочнице на заказе в EUR. Затем введите ключи для рабочего режима и выключите Sandbox mode.

OpenCart 4

1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_montonio_payment.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите Install (зелёная кнопка +) рядом с ним.

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Montonio Payment, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и ключи Montonio так же, как в шагах 3–5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только адрес уведомлений (см. Notification URL).

После новой установки способ оплаты изначально выключен, а режим песочницы включён.

Настройка

Все параметры находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Montonio Payment > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если отсутствуют ключи текущей среды (тогда способ оплаты не отображается при оформлении заказа), и если основная валюта магазина не EUR и не PLN, а также показывает Режим песочницы включён: платежи имитируются, и реальные деньги не списываются., пока песочница включена. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

При сохранении Title должен содержать от 1 до 128 символов, Sort Order должен быть целым числом (отрицательные числа допускаются), Total должен быть числом не меньше 0, а геозона и статусы заказов должны существовать. Если какое-либо значение неверно, ничего не сохраняется, и страница указывает на поле.

Montonio

Enable/Disable: Enable Montonio bank payments включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое видит покупатель при оформлении заказа. Оно также сохраняется в заказе и отображается на странице Montonio. По умолчанию: Bank payment (Montonio). Обязательное поле, до 128 символов.

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay directly from your bank account. You will be redirected to Montonio to choose your bank.

Sort Order: позиция Montonio среди способов оплаты при оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать Montonio только для платёжных адресов из выбранной геозоны. По умолчанию: All zones. Геозоны настраиваются в System > Localisation > Geo Zones.

Total: сумма заказа в основной валюте магазина, которую заказ должен достичь, прежде чем будет предложен Montonio. Оставьте поле пустым, чтобы предлагать Montonio при любой сумме.

API-ключи

Ключи можно получить в Montonio Partner System (на странице есть ссылка) в разделе Stores > your store > API keys. Ключи для песочницы и для рабочего режима различаются. Песочница использует только ключи песочницы, рабочий режим — только рабочие ключи.

Sandbox mode: использует песочницу Montonio (тестовые платежи, реальные деньги не списываются). Переключает одновременно адрес API Montonio и пару ключей. По умолчанию: включено. Выключайте его только после ввода рабочих ключей. Платежи, проведённые в другой среде, для подтверждений и возвратов по-прежнему используют ключи своей среды. Пока режим включён, покупатели видят на шаге Confirm Order сообщение РЕЖИМ ПЕСОЧНИЦЫ: тестовый платёж, реальные деньги не списываются.

Sandbox access key: ключ доступа (UUID) вашего магазина в песочнице Montonio.

Sandbox secret key: секретный ключ вашего магазина в песочнице Montonio.

Live access key: ключ доступа (UUID) вашего магазина в рабочей среде Montonio.

Live secret key: секретный ключ вашего магазина в рабочей среде Montonio.

Сохранённые секретные ключи больше никогда не показываются. Поле остаётся пустым и отображает Сохранено — оставьте пустым, чтобы не менять. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённый секретный ключ, установите флажок Clear the saved key on save под полем и нажмите Save.

Notification URL: адрес, на который Montonio отправляет уведомления о платежах. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_montonio_payment/notification, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_montonio_payment/payment/wcp_montonio_payment.notification. Он формируется из адреса витрины вашей установки OpenCart. Вводить его никуда не нужно: расширение передаёт его Montonio с каждым платежом.

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (незавершённый заказ). Заказ получает статус только после того, как Montonio подтвердит платёж. Каждое поле ниже перечисляет статусы заказов вашего OpenCart.

Order Status After Payment: статус, который устанавливается после проверенного платежа Montonio. По умолчанию: В обработке.

Payment On Hold Status: платёж требует внимания (см. Статусы заказов). По умолчанию: Ожидание, так как в OpenCart нет статуса «На удержании». Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Payment Failed Status: устанавливается, когда банк отклоняет платёж, который был удержан как авторизованный. По умолчанию: Неудачно.

Refunded Status: устанавливается после полного возврата платежа со страницы заказа. По умолчанию: Возвращено.

Дополнительно

Debug log: записывает события платежей в файл wc_mnt_debug.log.php в папке журналов OpenCart (storage/logs). Файл нельзя открыть через веб-браузер; при достижении 5 МБ он переносится в wc_mnt_debug.old.log.php. Ошибки и предупреждения записываются всегда, даже когда эта опция выключена. Ключи, токены и данные покупателей никогда не записываются. По умолчанию: выключено.

Log: показывает размер журнала и его последние записи. Нажмите Clear log, чтобы очистить его.

Delete data: если включено, при удалении расширения удаляются настройки платёжного шлюза и его журнал. Отключение расширения ничего не удаляет. Данные заказов (UUID Montonio, заметки) сохраняются всегда. По умолчанию: выключено.

Импорт / Экспорт

Export: Download JSON сохраняет настройки в файл JSON. Ключи доступа и секретные ключи не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые ключи доступа и секретные ключи сохраняются.

Уведомления о платежах

Montonio сообщает вашему магазину о каждом платеже с помощью подписанного токена. Токен поступает двумя способами: серверным уведомлением на адрес уведомлений и вместе с покупателем, когда он возвращается в магазин. Проверяется всё: подпись с помощью секретного ключа среды, в которой был создан платёж, срок действия, ваш ключ доступа и то, что платёж создан вашим магазином именно для этого заказа. Токен, подписанный ключом другой среды, отклоняется. Каждый статус применяется только один раз, поэтому повторные уведомления не добавляют заметок, писем или изменений остатков. Адрес уведомлений работает и тогда, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы платёжных расширений, а в OpenCart 4 расширение добавляет для этого стартовое действие, которое также пропускает возврат покупателя из Montonio.

Оформление заказа

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Bank payment (Montonio)). На шаге Confirm Order покупатель видит значок Montonio и ваше описание. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт платёж Montonio на сумму заказа в валюте заказа и перенаправляет покупателя на страницу оплаты Montonio. Там покупатель выбирает банк и оплачивает. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Сначала показываются банки страны платёжного адреса покупателя (для заказов в PLN — Польша). Платёж отображается как Order и номер заказа. Страница Montonio открывается на языке магазина, если это немецкий, английский, эстонский, финский, литовский, латышский, польский или русский; в остальных случаях — на английском.

Заказ отмечается как оплаченный только после подтверждения Montonio: по уведомлению или при возврате покупателя. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart с сообщением Your Montonio bank payment has been received. Если банк ещё не подтвердил платёж или заказ на удержании, страница показывает We are confirming your payment with Montonio. The order will be updated automatically — please do not pay again. Если банк позже отклонит авторизованный платёж, страница показывает Your Montonio payment was not completed. Please contact us about this order.

Если Montonio сообщает, что платёж ещё в ожидании, когда покупатель возвращается, отображается страница Payment confirmation с тем же текстом, кнопкой Check again и кнопкой Back to checkout. Check again запрашивает у Montonio текущий статус платежа. Уведомление устанавливает статус заказа, как только поступает.

Если платёж был отменён или отклонён, покупатель возвращается к оформлению заказа с одним из сообщений: The payment was cancelled or rejected by the bank. You can try again or choose another payment method., The payment was not completed. You can try again or choose another payment method. или Montonio could not complete the payment. Please try again or choose another payment method. На OpenCart 4 эти сообщения показываются над страницей оформления заказа. Корзина сохраняется. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, а OpenCart 4 оставляет один заказ для оформления и оплачивает тот же заказ новым платежом Montonio. Перед созданием нового платежа расширение запрашивает у Montonio информацию о предыдущей попытке для той же корзины. Если она уже оплачена, этот платёж подтверждается, покупатель переходит на страницу успеха, и второй платёж не производится.

OpenCart 4 сохраняет заказ оформления до показа страницы успеха. Если этот заказ к тому времени был закрыт без платежа (например, вы его отменили), покупатель возвращается к оформлению заказа с сообщением Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., в том числе когда он возвращается из Montonio, а следующее нажатие Confirm Order оплачивает новый заказ. В OpenCart 3 возврат покупателя по такому заказу показывает страницу успеха с пометкой, что платёж не был завершён. Если заказ оформления уже размещён, а корзина с тех пор изменилась, сообщение: Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. Изменение корзины, включая новое количество, считается новой корзиной, которой нужен собственный платёж. Заказ из корзины, которая была оплачена, а затем отменена или возвращена, больше не удерживает корзину.

Если Montonio не может начать платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, например Montonio temporarily unavailable. Please try again in a few minutes or choose another payment method. Техническая причина записывается в журнал.

Расширение поддерживает только банковские платежи (инициирование платежа). Оно не поддерживает платежи картами, BLIK, Apple Pay или Google Pay, Pay Later или рассрочку, доставку Montonio, подписки, сохранённые способы оплаты или выбор банка на вашем сайте.

Заказы и возвраты

Статусы заказов

Без статуса (незавершённый заказ): покупатель был перенаправлен в Montonio и не оплатил, Montonio сообщает, что платёж находится в ожидании, либо платёж был отменён или не завершён. В разделе Sales > Orders такие заказы показываются только с фильтром Order Status, установленным на Missing Orders.

Order Status After Payment (по умолчанию В обработке): Montonio подтвердил платёж (PAID) на точную сумму и в точной валюте заказа. Заметка показывает банк, UUID заказа Montonio, сумму и среду.

Payment On Hold Status (по умолчанию Ожидание): банк ещё не подтвердил платёж (AUTHORIZED); заказ переходит в статус Order Status After Payment, когда Montonio сообщает PAID. Заказ также переводится на удержание, если Montonio сообщил сумму или валюту, отличные от суммы заказа, если платёж из песочницы поступил, пока магазин работает в рабочем режиме (реальные деньги не получены), или если платёж поступил после того, как заказу был присвоен другой статус, например «отменён». Заметка объясняет ситуацию. Проверьте платёж в Montonio Partner System и выполните заказ или сделайте возврат платежа.

Payment Failed Status (по умолчанию Неудачно): банк отклонил платёж, который был удержан как авторизованный. Изменить статус может только последняя попытка оплаты заказа.

Refunded Status (по умолчанию Возвращено): платёж полностью возвращён через расширение.

Оплаченные или возвращённые заказы никогда не переоткрываются последующими уведомлениями. Если для уже оплаченного заказа поступает второй платёж, заказ не изменяется. Заметка просит вас вернуть второй платёж в Montonio Partner System.

Заметки — это записи в History заказа, которые покупатель не видит.

Вкладка VibeFox Montonio Payment

В разделе Sales > Orders откройте заказ, оплаченный через Montonio. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Montonio Payment показывает попытки оплаты заказа с датой, Montonio order UUID (с меткой Sandbox для тестовых платежей), суммой, банком, Montonio status и результатом. Ниже указаны суммы Paid / refunded, форма возврата, история возвратов и Montonio notes заказа. Вкладка доступна пользователям, которым разрешён доступ к расширению.

Возвраты

На вкладке VibeFox Montonio Payment введите сумму (подставляется сумма, которая ещё не возвращена), при желании причину (она сохраняется только в заметке к заказу) и нажмите Refund via Montonio. Подтвердите вопрос Вернуть эту сумму через Montonio? Это действие необратимо. Поддерживаются полный и частичный возвраты. Вам нужно право на изменение расширения (задаётся в System > Users > User Groups). Возвраты ограничены суммой, которую списал Montonio, поэтому после расхождения сумм можно вернуть не больше, чем покупатель фактически заплатил, а не сумму заказа. Возврат отправляется в ту среду, в которой был совершён платёж (песочница или рабочий режим), поэтому должны быть заданы ключи этой среды. Если Montonio не принимает возврат, вкладка показывает ошибку, и возврат не регистрируется. Отправленный возврат добавляется в историю возвратов и заметки вместе со своим статусом и идентификатором возврата Montonio. Полный возврат устанавливает заказу Refunded Status без уведомления покупателя и без возврата товаров на склад, как при ручной смене статуса. Частичный возврат статус не меняет. Возвраты доступны, когда Montonio сообщил, что платёж оплачен.

Позже Montonio подтверждает или отклоняет каждый возврат уведомлением. Подтверждение добавляется в заметки. Если Montonio отклонит возврат, заметка сообщит, что деньги покупателю не возвращены; проверьте это в Montonio Partner System и исправьте возврат в OpenCart.

Возвраты товаров в разделе Sales > Returns не возвращают деньги через Montonio. Возвраты, оформленные в Montonio Partner System, добавляются в заметки, когда Montonio о них сообщает. Статус заказа автоматически не меняется; при необходимости обновите его вручную.

Лицензионный ключ

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Montonio Payment — это первый блок на странице Extensions > Extensions > Payments > VibeFox Montonio Payment > Edit, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в маскированном виде, статус (например, дату, до которой лицензия активна, и ваш домен), а также кнопки Check now, чтобы повторно проверить статус, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: opencart-payment-montonio и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только пользователи-администраторы с правом Modify для расширения. Тексты блока следуют языку административной части (включены английский и русский).

Если ключ не принят, блок указывает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on и дату. После смены адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, расширение продолжает работать по последнему известному статусу.

Один ключ работает на одном домене. Удаление ключа из магазина не освобождает его слот домена. Освободите слот в своём аккаунте на vibefox.net.

Без активного ключа Montonio не показывается покупателям при оформлении заказа. Если платёж всё же запущен, покупатель видит сообщение This payment method is not available. Please choose another one. Пользователь-администратор, вошедший в административную часть в том же браузере, по-прежнему видит способ оплаты в магазине, помеченный как (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать расширение до покупки ключа. На OpenCart 4 этот предварительный просмотр недоступен: магазин не видит вход администратора, поэтому без активного ключа способ оплаты скрыт для всех. После того как вы один раз откроете страницу Edit, на Dashboard административной части появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты работают.

Когда лицензия истекает, расширение продолжает работать, но для обновлений и поддержки требуется продление. Статус проверяется автоматически при открытии Dashboard или страницы Edit в административной части: раз в день в течение первых 14 дней после ввода ключа, затем раз в неделю. Задание cron не требуется. При удалении расширения лицензионный ключ и статус лицензии всегда удаляются.

Устранение неполадок

Montonio не отображается при оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включён и заданы оба ключа текущей среды: Sandbox access key и Sandbox secret key в режиме песочницы или Live access key и Live secret key в рабочем режиме. Страница настроек показывает предупреждение, если ключи не заданы. Покупатель должен платить в EUR или PLN (валюте, выбранной в магазине). Также проверьте, что платёжный адрес входит в выбранную Geo Zone и что сумма заказа достигает значения Total, заданного в настройках.

Платёж прошёл, но заказ остаётся без статуса: уведомление не дошло до вашего магазина. Проверьте, что магазин доступен из интернета и что ключи в настройках относятся к среде платежа. Заказ также получает статус, когда покупатель возвращается в магазин после оплаты, когда он нажимает Check again и когда пытается снова оплатить ту же корзину.

Уведомление отвечает Invalid token: подпись токена, срок его действия или ключ доступа не совпали. Проверьте, что ключ доступа и секретный ключ скопированы верно и относятся к нужной среде, а также что правильно установлено время на сервере. Токен, подписанный ключом другой среды, также отклоняется.

Уведомление отвечает Payment does not belong to this order: платёж не был создан этим магазином для этого заказа. Это происходит, когда два магазина используют один аккаунт Montonio и одинаковые номера заказов.

Уведомление отвечает Gateway not configured: ключи Montonio не заданы или отсутствуют ключи среды платежа. Введите ключи; Montonio повторит уведомление.

Уведомление отвечает Temporarily unavailable: корзину в этот же момент подтверждал другой запрос, либо не удалось установить статус заказа. Montonio повторит уведомление. Причину смотрите в поле Log.

Покупатель видит ошибку после Confirm Order: посмотрите поле Log на странице расширения. Сообщение This payment method is not available. Please reload the checkout page. означает, что сессия оформления заказа больше не соответствует заказу или способ оплаты тем временем был отключён: покупателю нужно перезагрузить страницу оформления. Сообщение This payment method is temporarily unavailable. Please choose another payment method. обычно означает неверные или отсутствующие ключи. Сообщение Montonio could not start the payment. Please check your order details or choose another payment method. означает, что Montonio отклонил данные платежа; причина указана в журнале.

Заказ находится в статусе удержания после оплаты: прочитайте заметки на вкладке VibeFox Montonio Payment (см. Статусы заказов), затем выполните заказ или сделайте возврат платежа.

Платежи из песочницы не подтверждают реальный заказ: платёж из песочницы никогда не подтверждает заказ, пока магазин работает в рабочем режиме; вместо этого заказ переводится на удержание. Переключите Sandbox mode на нужную среду и используйте ключи этой среды.

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

Возврат завершается ошибкой с сообщением о среде: платёж был совершён в песочнице или в рабочем режиме, а ключи этой среды не заданы. Введите их и повторите попытку. Сообщение The order is being updated by a payment notification, try again in a moment. означает, что для того же заказа сейчас обрабатывается уведомление.

Для разработчиков: расширение вызывает события OpenCart wc_mnt_supported_currencies, wc_mnt_order_data и wc_mnt_locale, чтобы изменить поддерживаемые валюты, данные платежа и язык страницы Montonio.

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Montonio Payment. Лицензионный ключ и статус лицензии этого расширения удаляются всегда. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Orders, которые при повторной установке возвращаются к значениям по умолчанию. Также удаляется событие OpenCart расширения (в OpenCart 4 также его события и стартовое действие, которое пропускает уведомления в режиме обслуживания). Если Delete data включено, удаляются остальные настройки шлюза (название, описание, режим песочницы, ключи, журнал отладки) и журнал. Если выключено, они сохраняются для повторной установки. Записи о платежах и возвратах Montonio сохраняются всегда, поэтому заказы, оплаченные раньше, можно вернуть и после повторной установки. Существующие заказы сохраняют свои заметки о платежах.

В OpenCart 4, чтобы удалить и файлы расширения, после удаления перейдите в Extensions > Installer и нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Montonio Payment в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

Montonio — товарный знак его владельца. Это расширение не связано с Montonio и не одобрено Montonio.