VibeFox Moneris for OpenCart — Помощь

Требования

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

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

Валюта: CAD для канадской учётной записи Moneris, USD для устаревшей учётной записи Moneris USA. Способ оплаты отображается только тогда, когда валюта оформления заказа совпадает с валютой учётной записи.

HTTPS и PCI DSS: номера карт вводятся на странице оформления заказа и проходят через ваш сервер. Для реальных платежей требуются HTTPS и соответствие PCI DSS SAQ D. Если вы не можете это обеспечить, используйте вместо этого решение с размещённой платёжной страницей.

Учётная запись Moneris: вам нужны Store ID и API Token вашего магазина Moneris Gateway из раздела Moneris Merchant Resource Center > Admin > Store Settings. Для тестирования по умолчанию заполнен общедоступный тестовый магазин Moneris. Тестовые учётные данные и тестовые карты находятся на портале разработчиков Moneris.

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

Установка

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

OpenCart 3

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

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

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

4. Выберите страну учётной записи и введите Live Store ID и Live API Token. Тестовый режим включён по умолчанию и использует общедоступный тестовый магазин (store5 / yesguy для Канады, monusqa002 / qatoken для США).

5. Выберите тип транзакции и логотипы карт, затем включите Enable / Disable и нажмите Save.

6. Оформите тестовый заказ тестовой картой Moneris, затем выключите Test mode.

OpenCart 4

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

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

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

4. Введите лицензионный ключ и настройки так же, как в шагах 3–6 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Moneris Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками, пока включён тестовый режим, страница показывает Moneris gateway is in TEST MODE. No real charges will be made. В боевом режиме она предупреждает, если боевые поля содержат тестовые учётные данные Moneris (тогда способ оплаты скрывается при оформлении заказа), и если на магазине не включён SSL (в OpenCart 4 — когда адрес витрины начинается с http://). Также она предупреждает, если способ оплаты включён, но Store ID или API Token текущего режима пусты, и если валюта магазина по умолчанию не совпадает с валютой учётной записи Moneris; в обоих случаях способ оплаты скрывается при оформлении заказа. Без права изменять расширение страница показывает настройки, но не может их сохранить.

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

Moneris

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

Title: название способа оплаты, которое видит покупатель. Оно также сохраняется в заказе как название способа оплаты. По умолчанию: Кредитная карта (Moneris). В тестовом режиме к названию добавляется (Test Mode). Обязательно.

Description: текст, который отображается над полями карты на шаге Confirm Order. По умолчанию: Pay securely with your credit card.

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

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

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

Учётная запись Moneris

Ваши Store ID и API Token находятся в Moneris Merchant Resource Center в разделе Admin > Store Settings. Тестовые учётные данные и тестовые карты находятся на портале разработчиков Moneris. Этот раздел содержит ссылки на оба.

Moneris account country: канадские учётные записи списывают средства в CAD, американские — в USD. Способ оплаты отображается только тогда, когда валюта заказа совпадает. По умолчанию: Канада (CAD).

Test mode: использует тестовый шлюз QA Moneris и тестовые учётные данные; реальные списания не производятся. Возвраты, списания и отмены всегда отправляются в ту среду, в которой был совершён платёж. Покупатели видят TEST MODE: use a Moneris test card, no real charges are made. над полями карты. По умолчанию: включено.

Live Store ID: Store ID для боевого режима, например monca01234.

Live API Token: боевой API Token.

Test Store ID: общедоступный тестовый магазин Moneris: store5 (Канада) или monusqa002 (США). По умолчанию: store5.

Test API Token: общедоступный тестовый токен: yesguy (Канада) или qatoken (США). По умолчанию: yesguy.

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

Оплата

Transaction type: способ списания средств с карты. По умолчанию: Purchase.

Card logos: бренды карт, которые отображаются вместе со способом оплаты при оформлении заказа: Visa, Mastercard, Discover, American Express, JCB. Принимаемые бренды зависят от вашей учётной записи Moneris. По умолчанию: Visa и Mastercard.

Заказы

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

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

Authorized Status: предавторизация: средства только зарезервированы, но ещё не списаны. Спишите их на вкладке заказа или переведя заказ в оплаченный статус. По умолчанию: Ожидание.

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

Canceled Status: устанавливается кнопкой Void pre-authorization (cancel order) на вкладке заказа. Перевод заказа в этот статус снимает (аннулирует) незаписанную предавторизацию. По умолчанию: Отменено.

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

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Credit card (Moneris)). На шаге Confirm Order покупатель видит ваше описание, логотипы карт и поля Card number, Expiry (MM/YY) и Card code (CVC). Все три поля обязательны. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options; поля карты затем появляются в блоке подтверждения заказа внизу страницы оформления, над кнопкой Confirm Order. Когда покупатель нажимает Confirm Order, ваш сервер отправляет карту в Moneris на сумму заказа и сразу получает результат. Перенаправления и вебхука нет. Данные карты используются только для этого одного запроса; они никогда не сохраняются, а в журнале отображаются только последние четыре цифры.

Заказ получает статус только по одобренному ответу Moneris, стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков. Корзина очищается, и покупатель видит страницу успешного оформления заказа OpenCart. При предавторизации заказ ждёт в Authorized Status, пока вы не спишете средства. Если Moneris обработал сумму, отличающуюся от суммы заказа, заказ получает статус проверки с примечанием.

Если карта отклонена, покупатель остаётся на шаге Confirm Order с сообщением Your card was declined и причиной от Moneris и может проверить данные карты или использовать другую карту. Заказ не получает статуса; причина отказа также записывается в журнал. Если Moneris не смог обработать запрос (например, из-за неверного Store ID или API Token), покупатель видит The payment could not be processed. Please try again or use another payment method. Причина записывается в журнал. Неверные поля карты дают короткие сообщения, например Please enter your card details., Invalid card number. или Invalid card expiry date., и в Moneris ничего не отправляется.

Повторный клик во время обработки платежа показывает A payment for this order is already being processed. Please wait a moment and check your order status before trying again. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, OpenCart 4 оставляет один заказ на оформление, а после отклонённой карты покупатель оплачивает тот же заказ. В любом случае расширение считает все заказы одной корзины одним платежом: корзина, которая уже оплачена или результат которой неизвестен, никогда не списывается повторно, а покупатель переходит на страницу успеха. OpenCart 4 хранит заказ в оформлении до показа страницы успеха. Если у этого заказа уже есть статус и в корзине снова есть товары (например, платёж прошёл, но страница успеха не показалась, и покупатель добавил товары), либо заказ был отменён, возвращён или аннулирован в это время, покупатель возвращается на страницу оформления на шаг Confirm Order, а следующее нажатие Confirm Order оплачивает новый заказ. Над страницей оформления покупатель видит This order was cancelled or refunded by the store, so it cannot be paid again. Please check your cart and confirm the new order., если заказ был закрыт, или This order has already been paid, and your cart now holds a new purchase. Please check your cart and confirm the new order., если он был оплачен за предыдущую корзину.

Если Moneris не отвечает (сетевая ошибка или тайм-аут), расширение отправляет в Moneris проверку статуса с тем же идентификатором заказа Moneris, чтобы выяснить, прошла ли транзакция. Если в Moneris нет такой транзакции, покупатель может оплатить снова. Если проверка статуса тоже не получает ответа, заказ получает статус проверки с примечанием, в котором указан идентификатор заказа Moneris, и покупателя не просят платить второй раз. Если платёж прошёл, но статус заказа установить не удалось, покупатель видит Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again.

В расширении нет сохранённых карт и Moneris Vault, подписок, Apple Pay, Google Pay или Interac Online, Moneris Checkout или Hosted Tokenization, 3-D Secure, AVS или Kount, а также ценообразования в нескольких валютах.

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

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

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

Order Status After Payment (по умолчанию В обработке): покупка одобрена или предавторизация списана. Примечание показывает сумму, Moneris Trans ID и чек.

Authorized Status (по умолчанию Ожидание): предавторизация одобрена и ждёт списания.

On Hold (Review) Status (по умолчанию Ожидание): обработанная сумма отличалась от суммы заказа, либо Moneris не подтвердил результат. Примечания объясняют это.

Canceled Status (по умолчанию Отменено): для заказа с предавторизацией зарезервированные средства были освобождены (аннулированы).

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

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

Вкладка VibeFox Moneris Gateway

В разделе Sales > Orders откройте заказ, оплаченный через Moneris. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Moneris Gateway показывает Trans ID (а после списания — Trans ID предавторизации), Moneris order ID, Receipt, Transaction type и его состояние (не списано, списано или освобождено), Account / environment с меткой Test mode для тестовых платежей, Card с кодом авторизации, суммы Authorized / charged / refunded, кнопки списания, отмены и возврата, историю возвратов и Moneris notes заказа. Если платёж не подтверждён, вкладка предлагает найти идентификатор заказа Moneris в Merchant Resource Center. Вкладка показывается пользователям, которые имеют доступ к расширению; списание, отмена и возврат требуют права изменять расширение (задаётся в System > Users > User Groups).

Списание и отмена

Чтобы списать предавторизацию, нажмите Capture payment на вкладке и подтвердите Capture the pre-authorized amount through Moneris?, или измените статус заказа через Add History на оплаченный статус, например Order Status After Payment или другой статус OpenCart «В обработке» или «Выполнен». Списывается сумма заказа за вычетом возвратов; она не может быть больше авторизованной суммы. После списания кнопкой заказ получает Order Status After Payment. Если Moneris отклоняет списание, статус не меняется, письмо не отправляется, Add History показывает причину вместо сообщения об успехе, а примечание объясняет: Moneris: status not changed — the pre-authorization could not be captured с указанием причины. Предавторизации Moneris истекают через несколько дней, поэтому списывайте их вовремя.

Чтобы освободить средства, нажмите Void pre-authorization (cancel order) и подтвердите, либо переведите заказ в Canceled Status. Перевод заказа в Refunded Status также освобождает открытую предавторизацию. Если освободить не удалось, примечание попросит вас сделать это в Merchant Resource Center.

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

Возвраты

На вкладке VibeFox Moneris Gateway введите Amount (сумма, которая ещё не возвращена, подставляется автоматически), при необходимости Reason (optional), и нажмите Refund via Moneris. Подтвердите вопрос Refund this amount through Moneris? This cannot be undone. Поддерживаются полные и частичные возвраты. Возвраты ограничены суммой, которую Moneris фактически списал; поэтому после расхождения суммы вы можете вернуть не больше того, что заплатил покупатель, а не сумму заказа. Предавторизацию можно вернуть только после её списания; до этого аннулируйте её, чтобы освободить средства. Возврат отправляется в ту среду и на ту учётную запись, в которых был совершён платёж, поэтому учётные данные этого режима должны оставаться заполненными. Если Moneris не принимает возврат, вкладка показывает Refund failed с причиной, и возврат не записывается. Успешный возврат добавляется в историю возвратов и примечания вместе с Moneris Trans ID. Полный возврат устанавливает заказу Refunded Status; частичный возврат статус не меняет. Списание, отмена и возврат напрямую меняют статус заказа без уведомления покупателя и без возврата товаров на склад, как при ручной смене статуса.

Возвраты товаров в разделе Sales > Returns не возвращают деньги через Moneris.

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

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

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

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

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

Moneris не появляется при оформлении заказа: проверьте, что лицензия активна, Enable / Disable включено и в текущем режиме есть Store ID и API Token. В боевом режиме боевые поля должны содержать ваши боевые учётные данные, а не тестовые учётные данные Moneris. Проверьте, что валюта оформления заказа совпадает с валютой учётной записи (CAD для Канады, USD для американской учётной записи), что платёжный адрес входит в выбранную Geo Zone и что сумма заказа достигает Total, заданного в настройках.

Платёж прошёл, но заказ находится в статусе проверки: у расширения нет вебхука; результат поступает только из ответа Moneris. Прочитайте Moneris notes на вкладке. Если Moneris не подтвердил результат, значит, Moneris не ответил и проверка статуса тоже не удалась. Найдите идентификатор заказа Moneris в Merchant Resource Center: если транзакция там есть, отправьте заказ (и при необходимости верните платёж там); если нет, отмените заказ или попросите покупателя оплатить снова. Если сумма отличалась, проверьте заказ и выполните его или верните платёж.

Покупатель видит This payment method is not available. Please reload the checkout page.: сессия оформления заказа больше не соответствует заказу, способ оплаты тем временем выключили, или отсутствуют учётные данные текущего режима (либо в боевом режиме используются тестовые учётные данные Moneris).

Покупатель видит This payment method does not support the order currency.: валюта заказа не совпадает с валютой учётной записи Moneris.

Покупатель видит ошибку при оплате: посмотрите поле Log на странице расширения. Ошибки записываются всегда; включите Debug log, чтобы увидеть полные запросы и ответы.

Списание не удаётся: у заказа нет предавторизации, ожидающей списания, сумма заказа равна нулю, или сумма больше авторизованной. Кроме того, предавторизации Moneris истекают через несколько дней.

Возврат, списание или отмена не удаются с сообщением о режиме или учётной записи: платёж был совершён в тестовом или боевом режиме, а учётные данные этого режима не заданы, либо платёж был совершён с учётной записью Moneris другой страны. Введите учётные данные или обработайте платёж в Merchant Resource Center.

Атаки перебора карт: формы ввода карт напрямую являются мишенью для перебора карт. Используйте правила eFraud или правила по частоте в вашей учётной записи Moneris, а также расширение CAPTCHA или ограничения частоты запросов для вашего магазина.

Удаление

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

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

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