VibeFox Mollie for OpenCart — Помощь

Требования

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

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

Валюта: валюта оформления заказа должна входить в список валют, поддерживаемых Mollie: AED, AUD, BGN, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, ISK, JPY, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TWD, USD, ZAR. Для других валют способ оплаты скрывается при оформлении заказа. Какие способы оплаты предлагает Mollie, зависит от валюты и вашей учётной записи.

Доступ в интернет для вашего магазина: Mollie отправляет вебхуки в ваш магазин, поэтому сайт должен быть доступен из интернета. Без вебхуков заказы получают статус, когда покупатель возвращается из Mollie.

Учётная запись Mollie: вам нужны API-ключи из раздела Mollie Dashboard > Developers > API keys. Тестовые ключи начинаются с test_, боевые — с live_. Никакие другие ключи или секреты не нужны. Сами способы оплаты включаются в вашей учётной записи Mollie.

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

Установка

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

OpenCart 3

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

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

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

4. Введите ваши тестовые и боевые API-ключи (см. Configuration). В Mollie настраивать вебхук не нужно.

5. Включите Enable/Disable и нажмите Save. Оставьте Test Mode включённым, пока не выполните тестовый платёж, а затем выключите его.

OpenCart 4

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

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

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

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

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

Настройка

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

При сохранении в поле Title должно быть от 1 до 128 символов, Sort Order должно быть целым числом, а Total — числом не меньше 0; в противном случае ничего не сохраняется. API-ключ, который не начинается с test_ или live_ и за которым не следуют не менее 30 букв и цифр, не сохраняется: страница показывает Settings saved, except the API key shown in red., ошибка указывает на ключ, а ранее сохранённый ключ остаётся.

Checkout

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

Title: название способа оплаты, которое показывается покупателю при оформлении заказа. Оно также сохраняется в заказе как название способа оплаты. По умолчанию: Mollie. Обязательно.

Description: текст, который показывается покупателю на шаге Confirm Order, над кнопкой подтверждения. По умолчанию: Pay securely via Mollie.

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

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

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

API-ключи

Ваши API-ключи находятся в Mollie Dashboard в разделе Developers > API keys; этот раздел содержит ссылку на эту страницу. Тестовые и боевые ключи различаются.

Test Mode: использует тестовый API-ключ для новых платежей. Реальные платежи не проводятся. На тестовой странице оплаты Mollie можно выбрать результат платежа. Покупатели видят Test mode: no real payment will be made. на шаге Confirm Order. Платежи, сделанные в другом режиме, для проверки статуса и возвратов по-прежнему используют ключ своего режима. По умолчанию: включено.

Test API Key: ваш тестовый API-ключ Mollie (начинается с test_).

Live API Key: ваш боевой API-ключ Mollie (начинается с live_).

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

Вебхук

Webhook URL: показывается для справки. Настраивать вебхук не нужно: расширение отправляет этот адрес в Mollie с каждым платежом. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_mollie_gateway/webhook, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_mollie_gateway/payment/wcp_mollie_gateway.webhook. Он формируется из адреса витрины вашей установки OpenCart. Он должен быть доступен из интернета, иначе заказы получают статус только тогда, когда покупатель возвращается из Mollie.

Заказы

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

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

Awaiting Mollie Payment Status: покупатель выбрал банковский перевод на странице Mollie; заказ автоматически отмечается как оплаченный, когда Mollie получает деньги. По умолчанию: Ожидание.

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

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

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

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

Logging: записывает вызовы API и вебхуки в файл molg_debug.log.php в папке журналов OpenCart (storage/logs). Открыть файл через браузер нельзя. Ошибки записываются всегда, даже если этот параметр выключен. Ключи API и данные покупателей никогда не записываются. По умолчанию: выключено.

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

Delete Data on Uninstall: если включено, при удалении расширения удаляются настройки шлюза и его журнал. Идентификаторы платежей Mollie, сохранённые с заказами (платежи, возвраты), всегда сохраняются. По умолчанию: выключено.

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Mollie). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to Mollie to choose a payment method and pay. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт платёж Mollie на сумму заказа в валюте заказа (JPY и ISK без десятичных знаков) с описанием Order # и номером заказа и отправляет покупателя на размещённую страницу оплаты Mollie. Там покупатель выбирает один из способов оплаты, включённых в вашей учётной записи Mollie, и платит. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа.

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

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

Если платёж был отменён, не прошёл, истёк или не завершён, покупатель возвращается к оформлению заказа с сообщением, например You cancelled the Mollie payment. You can try again or choose another payment method. или The Mollie payment has expired. Please try again or choose another payment method. В OpenCart 4 эти сообщения показываются над страницей оформления заказа. Корзина сохраняется. Если Mollie недоступен или ещё не принял решение, появляется страница Payment confirmation, которая просит покупателя не платить повторно и предлагает кнопку Check again; вебхук устанавливает статус заказа, как только получает уведомление.

OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, а OpenCart 4 оставляет один заказ на оформление и оплачивает тот же заказ новым платежом Mollie. В любом случае расширение считает все заказы одной корзины одним платежом. Когда покупатель платит повторно, ещё открытый платёж Mollie на ту же сумму используется снова, вместо создания второго платежа к оплате. Если сумма изменилась, старый открытый платёж отменяется в Mollie, если Mollie это разрешает. Если старый платёж тем временем был оплачен, этот платёж подтверждается, и покупатель переходит на страницу успеха без нового платежа.

OpenCart 4 сохраняет заказ на оформлении до показа страницы успеха. Если этот заказ был закрыт без оплаты (например, истёк срок банковского перевода или вы его отменили или вернули), покупатель возвращается к оформлению заказа с сообщением Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order., а следующее нажатие Confirm Order оплачивает новый заказ. Заказ корзины, который был оплачен, а затем отменён или возвращён, больше не удерживает корзину.

Если Mollie не может начать платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, например The payment provider could not be reached. Please try again in a moment., This payment method is temporarily unavailable. Please choose another payment method. (неверный API-ключ) или Mollie cannot accept a payment of this amount or currency. Please choose another payment method. Техническая причина записывается в журнал.

Вебхук также работает, пока магазин находится в режиме обслуживания, потому что OpenCart 3 пропускает запросы платёжных расширений, а на OpenCart 4 расширение для этого добавляет стартовое действие, которое также пропускает возврат покупателя из Mollie.

Способ Mollie покупатель выбирает на странице Mollie, а не в вашем оформлении заказа. Расширение не поддерживает подписки и регулярные платежи, сохранённые карты и мандаты, поля для карт на вашем сайте, экспресс-кнопки Apple Pay или PayPal и Orders API, поэтому способы, требующие позиций заказа (например, некоторые варианты Klarna, Billie или in3), для этих платежей Mollie не предлагает. Авторизованные платежи списываются или отменяются в Mollie Dashboard, а не из OpenCart.

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

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

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

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

Awaiting Mollie Payment Status (по умолчанию Ожидание): покупатель выбрал банковский перевод на странице Mollie. Заказ переходит в статус оплаченного, когда Mollie получает деньги.

Mollie Payment On Hold Status (по умолчанию Ожидание): авторизованный платёж ожидает списания, Mollie сообщил о чарджбэке, оплаченная сумма или валюта отличались от заказа, тестовый платёж был оплачен, пока магазин работает в боевом режиме (деньги не получены), или платёж поступил после того, как заказ получил другой статус (например, был отменён). Примечание объясняет ситуацию. Проверьте платёж в Mollie Dashboard, затем обработайте заказ или верните платёж.

Payment Error Status (по умолчанию Неудачно): банковский перевод или авторизация заказа не прошли, истекли или были отменены.

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

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

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

Вкладка VibeFox Mollie Gateway

В разделе Sales > Orders откройте заказ, оплаченный через Mollie. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Mollie Gateway показывает идентификатор Mollie payment с меткой Test mode для тестовых платежей, Method, Status платежа, суммы Paid / refunded, форму возврата, историю возвратов (дата, идентификатор возврата, сумма, режим, статус Mollie, причина) и Mollie notes заказа. Вкладка показывается пользователям, которые имеют доступ к расширению.

Возвраты

На вкладке VibeFox Mollie Gateway введите Amount (сумма, которая ещё не возвращена, подставляется автоматически), при необходимости Reason (optional) и нажмите Refund via Mollie. Подтвердите вопрос Refund this amount through Mollie? This cannot be undone. Поддерживаются полные и частичные возвраты. Вам нужно право изменять расширение (задаётся в System > Users > User Groups). Возвраты выполняются в той сумме и валюте, которые списал Mollie, поэтому после расхождения суммы вы можете вернуть не больше того, что покупатель фактически заплатил, а не сумму заказа. Возврат отправляется по платежу, которым фактически оплачен заказ, с API-ключом того режима, в котором он был совершён, поэтому ключ этого режима должен быть задан. Если Mollie отклоняет возврат или сообщает о нём как о неудачном или отменённом, вкладка показывает сообщение и возврат не записывается. Успешный возврат добавляется в историю возвратов и примечания вместе с идентификатором возврата Mollie. Полный возврат устанавливает заказу Refunded Status без уведомления покупателя и без возврата товаров на склад, как при ручной смене статуса. Частичный возврат статус не меняет. Возвраты доступны, как только Mollie сообщил, что платёж оплачен.

Возвраты товаров в разделе Sales > Returns не возвращают деньги через Mollie. Возвраты, созданные в Mollie Dashboard, в заказе не отображаются; чарджбэк добавляет примечание.

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

Расширение работает с лицензионным ключом VibeFox с сайта vibefox.net. Блок лицензии License — VibeFox Mollie Gateway является первым блоком на странице Extensions > Extensions > Payments > VibeFox Mollie Gateway > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-payment-mollie и ссылка 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. Если сервер лицензий недоступен, расширение продолжает работать по последнему известному статусу.

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

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

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

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

Mollie не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и в текущем режиме есть API-ключ: Test API Key в тестовом режиме, Live API Key в боевом режиме. Проверьте, что валюта оформления заказа поддерживается Mollie, что платёжный адрес входит в выбранную Geo Zone и что сумма заказа достигает Total, заданного в настройках. Страница настроек показывает предупреждение при отсутствии ключа и при неподдерживаемой валюте магазина.

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

Вебхук отвечает Unknown payment.: платёж создан не этим магазином или Mollie не знает его для API-ключа своего режима, например платёж другой учётной записи Mollie.

Вебхук отвечает Payment ID mismatch.: платёж не принадлежит заказу, для которого был создан. Ничего не изменяется.

Вебхук отвечает Failed to fetch payment.: не удалось связаться с API Mollie или не задан API-ключ режима этого платежа. Mollie повторит вебхук позже.

Вебхук отвечает Temporarily unavailable.: корзину в тот же момент обрабатывал другой запрос или не удалось установить статус заказа. Mollie повторит вебхук. Включите Logging, чтобы увидеть причину.

URL вебхука показывает в браузере Method not allowed.: это нормально. URL принимает только запросы от Mollie.

API-ключ не сохраняется: ключ должен начинаться с test_ или live_, за которым следуют не менее 30 букв и цифр. Скопируйте его заново из Mollie Dashboard.

Покупатель видит ошибку после Confirm Order: посмотрите поле Log на странице расширения. В нём указаны HTTP-код и сообщение Mollie. 401 означает неверный API-ключ; 422 указывает на поле запроса, например сумму или валюту, которые Mollie не принимает. This payment method is not available. означает, что сессия оформления заказа больше не соответствует заказу или способ оплаты тем временем выключили: покупателю нужно перезагрузить оформление заказа.

Заказ в статусе «На удержании»: прочитайте примечания на вкладке VibeFox Mollie Gateway (см. Order statuses), затем обработайте заказ или верните платёж.

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

Для разработчиков: расширение вызывает события OpenCart molg_supported_currencies (список валют) и molg_payment_data (запрос на оплату и заказ, до создания платежа Mollie).

Удаление

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

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

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