VibeFox GMO for OpenCart — Помощь

Требования

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

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

Валюта: японская иена (JPY). GMO-PG списывает деньги только в иенах, поэтому способ оплаты показывается только тогда, когда валюта оформления заказа у покупателя — JPY. Если в вашем магазине нет JPY, добавьте её в System > Localisation > Currencies. Сумма — это итог заказа, пересчитанный по курсу JPY магазина и округлённый до целых иен.

Учётная запись GMO Payment Gateway: договор мерчанта GMO-PG с Link Type Plus. Вам нужны Shop ID, Shop password и Link Type Plus Config ID (設定ID) тестовой и/или рабочей среды, а также включённое уведомление о результате (結果通知) в консоли магазина GMO-PG (см. Configuration). Site ID и Site password не используются.

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

Установка

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

OpenCart 3

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

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

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

4. Введите Shop ID, Shop password и Config ID тестовой и/или рабочей среды и выберите Environment.

5. В консоли магазина GMO-PG включите 結果通知 (result notification) и укажите URL уведомления, который показан в настройках (см. Configuration).

6. Включите Enable/Disable и нажмите Save. Проведите тестовый платёж в тестовой среде, затем переключите Environment на рабочую среду.

OpenCart 4

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

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

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

4. Введите лицензионный ключ, учётные данные GMO-PG и URL уведомления так же, как в шагах с 3 по 6 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только URL уведомления (см. Уведомления об оплате (結果通知)).

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox GMO Payment Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если валюта магазина по умолчанию не JPY, и если у текущей среды не заполнены Shop ID, Shop password или Config ID (тогда способ оплаты скрыт при оформлении заказа). Она также показывает, какая среда активна: TEST — payments go to pt01.mul-pay.jp with the test credentials, no real money is charged. или PRODUCTION — payments go to p01.mul-pay.jp. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

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

GMO Payment Gateway — банковская карта

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

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

Description: описание способа оплаты на шаге Confirm Order, над кнопкой подтверждения. По умолчанию: You will be redirected to the secure GMO Payment Gateway page to pay by credit card.

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

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

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

Учётная запись GMO-PG

Shop ID и Shop password находятся в консоли GMO-PG в разделе Shop management > Shop information, а Config ID — в разделе Link Type Plus > Settings (設定ID). У тестовой и рабочей сред разные учётные данные.

Environment: какая среда GMO-PG принимает новые платежи.

Test (sandbox): pt01.mul-pay.jp с тестовыми учётными данными (по умолчанию).

Production (live): p01.mul-pay.jp с рабочими учётными данными.

Production Shop ID: Shop ID рабочей среды.

Production Shop password: Shop password рабочей среды.

Production Config ID: Link Type Plus config ID (設定ID), зарегистрированный в консоли GMO-PG.

Test Shop ID: Shop ID тестовой среды.

Test Shop password: Shop password тестовой среды.

Test Config ID: Link Type Plus config ID (設定ID) тестовой среды.

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

Оплата

Capture: когда списывается оплата с карты.

Capture immediately (即時売上): карта списывается сразу (по умолчанию).

Authorize only (仮売上): сумма только авторизуется, и заказ получает статус GMO-PG payment on hold, пока вы не спишете её командой Capture payment (GMO-PG) на вкладке заказа или в консоли GMO-PG, до истечения срока авторизации.

Order status after payment: какой статус получает оплаченный заказ.

Processing: статус, выбранный в поле Processing раздела Order statuses (по умолчанию).

Completed: статус, выбранный в поле Completed раздела Order statuses. Подходит для виртуальных и загружаемых товаров.

Уведомления об оплате (結果通知)

Уведомление о результате сообщает вашему магазину, что оплата произведена. Оно обязательно. В консоли GMO-PG включите 結果通知 (result notification) и укажите URL, который показан в поле Notification URL в этом разделе. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_gmo_payment/notify, в OpenCart 4 — так: https://your-store/index.php?route=extension/wcp_gmo_payment/payment/wcp_gmo_payment.notify. Его составляют из адреса витрины вашей установки OpenCart. Копируйте URL точно так, как он показан в настройках. Он должен быть доступен из Интернета; режим обслуживания его не блокирует.

Уведомления GMO-PG не подписаны, поэтому расширение никогда не доверяет их содержимому. Уведомление должно прийти с одного из настроенных Shop ID и относиться к платежу, созданному этим магазином, в той среде, где платёж был сделан. Затем расширение запрашивает у GMO-PG транзакцию (SearchTrade) с вашим Shop password и меняет заказ только по этому ответу. Уведомление, которому не соответствует реальная транзакция, ничего не меняет. Транзакции, созданные не магазином, например сделанные в консоли GMO-PG, подтверждаются и игнорируются. Если расширение не может проверить уведомление, оно отвечает так, чтобы GMO-PG отправил его повторно.

Без уведомления заказ получает статус, только когда покупатель возвращается в магазин после оплаты.

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

OpenCart создаёт заказ на шаге Confirm Order без статуса (пропавший заказ, missing order). Заказ получает статус только после того, как GMO-PG подтвердит оплату. Каждое поле перечисляет статусы заказов вашего OpenCart. В OpenCart нет статуса On hold, поэтому авторизация или платёж на другую сумму получает статус ожидания, указанный ниже, и примечание к заказу.

Processing: оплаченный заказ, когда Order status after payment равен В обработке. По умолчанию: В обработке.

Completed: оплаченный заказ, когда Order status after payment равен Выполнен. По умолчанию: Выполнен.

GMO-PG payment on hold: только авторизован (ожидает списания) или сумма не совпадает с заказом. По умолчанию: Ожидание. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Cancelled: авторизация или платёж в ожидании, отменённые в GMO-PG, либо авторизация, возвращённая полностью. По умолчанию: Отменен.

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

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Credit card). На шаге Confirm Order покупатель видит ваше описание; в тестовой среде над ним показывается плашка TEST — GMO-PG test environment, no real charges. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Когда покупатель нажимает Confirm Order, расширение создаёт платёж GMO-PG Link Type Plus на сумму заказа в целых иенах и переводит покупателя на страницу оплаты GMO-PG. Там покупатель платит банковской картой. 3-D Secure 2.0 обрабатывает GMO-PG, а адрес электронной почты покупателя передаётся ему для 3-D Secure. Страница оплаты открывается на японском, китайском или английском языке в зависимости от языка заказа. В GMO-PG платёж отображается с префиксом OC- и номером заказа. Никакие другие данные покупателя не передаются.

После оплаты покупатель возвращается в ваш магазин. Подписанный результат проверяется по Shop password среды, в которой прошёл платёж, и заказ отмечается оплаченным только после того, как GMO-PG это подтвердит: запросом SearchTrade на сервере, когда покупатель возвращается, или уведомлением о результате. Обе схемы используют одну и ту же логику, поэтому платёж никогда не применяется дважды. Затем заказ получает статус стандартным способом OpenCart, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Если GMO-PG ещё не подтвердил платёж, страница Payment confirmation показывает текст Your card payment is being confirmed by GMO Payment Gateway. You will receive an e-mail as soon as it is confirmed. с кнопками Check again и Back to checkout; уведомление устанавливает статус заказа, как только поступит.

Если карта отклонена или платёж не проходит на странице GMO-PG, покупатель возвращается к оформлению заказа с сообщением The card payment was declined or could not be completed. Please try again or use another card. Если покупатель уходит со страницы GMO-PG, не заплатив, выводится сообщение The payment was not completed. You can try again or choose another payment method. Корзина сохраняется. На OpenCart 4 эти сообщения выводятся над страницей оформления заказа. Каждая новая попытка (OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, OpenCart 4 обновляет заказ, который создаётся при оформлении) отменяет предыдущие неоплаченные платёжные ссылки корзины. Если предыдущая ссылка к тому времени уже оплачена, этот платёж подтверждается, и новая ссылка не создаётся.

OpenCart 4 сохраняет заказ на этапе оформления до показа страницы успешного оформления заказа. Если за это время заказ закрыт без оплаты (например, он был отменён в GMO-PG или вами), покупатель возвращается к оформлению заказа с сообщением Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., а следующий Confirm Order оплачивает новый заказ этой корзины. Если этот заказ уже оплачен, но корзина с тех пор изменилась, в том числе изменилось количество, выводится сообщение 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. Оплаченный заказ никогда не показывается как оплаченный для другой корзины.

Оплатить можно заказы на сумму от 1 до 9,999,999 JPY; более крупные суммы скрывают способ оплаты. Если платёж не удаётся начать, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, например Card payment could not be started. Please try again or choose another payment method., а причина записывается в журнал.

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

Расширение принимает платежи банковскими картами только в JPY и всегда на странице GMO-PG. Оно не поддерживает других способов оплаты GMO-PG, нескольких валют, сохранённых карт и регистрации участников GMO-PG, подписок и периодических списаний, а также формы ввода карты на сайте.

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

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

No status (missing order): покупатель был направлен в GMO-PG и не оплатил, или GMO-PG ещё не подтвердил платёж. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в значение Missing Orders.

Processing or Completed status: платёж подтверждён; статус определяется полем Order status after payment. Примечание показывает сумму, статус GMO-PG, транзакцию и то, как был подтверждён платёж (уведомлением или возвратом покупателя).

GMO-PG payment on hold (authorized): при Authorize only (仮売上) сумма была авторизована. Спишите её командой Capture payment (GMO-PG) или в консоли GMO-PG до истечения срока авторизации. После списания заказ получает статус оплаченного. Если авторизация отменена в GMO-PG, заказ получает статус Cancelled.

GMO-PG payment on hold after payment: GMO-PG сообщил сумму, отличную от итога заказа. Примечание объясняет это. Проверьте заказ и выполните его или сделайте возврат платежа.

Refunded: платёж полностью возвращён через расширение. Полный возврат авторизации, которая так и не была списана, устанавливает статус Cancelled.

Если по уже оплаченному заказу или по той же корзине в другом заказе приходит второй платёж, оплаченный заказ не меняется. Примечание просит вас вернуть дубликат в консоли GMO-PG. Если платёж приходит для заказа, который уже имеет статус без платежа GMO-PG, добавляется только примечание.

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

Вкладка VibeFox GMO Payment Gateway

В Sales > Orders откройте заказ, оплаченный через GMO-PG. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox GMO Payment Gateway показывает GMO OrderID (с меткой TEST для тестовых платежей), Transaction ID, Status со статусом GMO-PG, Paid / refunded, кнопку списания и форму возврата, историю возвратов и GMO-PG notes заказа. Вкладка показывается пользователям, которые имеют доступ к расширению; списание и возвраты требуют права на изменение расширения (настраивается в System > Users > User Groups).

Списание

Capture payment (GMO-PG) появляется на вкладке заказа в ожидании, который был только авторизован. Подтвердите Capture the authorized GMO-PG payment? Расширение проверяет транзакцию в GMO-PG и списывает авторизованную сумму; после этого заказ получает статус оплаченного. Если транзакция больше не авторизована, например потому что она уже была списана в консоли GMO-PG, сообщение покажет текущий статус. Списание, сделанное в консоли GMO-PG, приходит через уведомление о результате.

Возвраты

На вкладке введите Amount (подставляется сумма, которая ещё не возвращена), при необходимости Reason (optional), и нажмите Refund via GMO-PG. Подтвердите Refund this amount through GMO-PG? Поддерживаются полные и частичные возвраты в целых иенах. Лимит — это сумма, которую GMO-PG фактически списал и ещё удерживает, а не итог заказа. Возврат всей оставшейся суммы отменяет транзакцию GMO-PG, а решение о том, будет ли это отмена или возврат, принимает GMO-PG. Частичный возврат уменьшает сумму транзакции. Возврат отправляется в ту среду, где прошёл платёж, поэтому должны быть заполнены Shop ID и Shop password этой среды. Если GMO-PG не принимает возврат, вкладка показывает ошибку, и возврат не регистрируется. Успешный возврат добавляется в историю возвратов и примечания. Полный возврат устанавливает статус Refunded без уведомления покупателя и без возврата товаров на склад, так же как при ручном изменении статуса. Частичный возврат статус не меняет.

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

Возвраты и отмены, сделанные в консоли GMO-PG, приходят через уведомление о результате и добавляются в примечания. Статус заказа не меняется автоматически, кроме случая авторизации или платежа в ожидании, отменённых в GMO-PG. При необходимости обновите его вручную.

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

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

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

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

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

Credit card does not appear at checkout: проверьте, что лицензия активна, что Enable/Disable включено, что валюта оформления заказа — JPY и что у текущей среды заполнены Shop ID, Shop password и Config ID. Суммы выше 9,999,999 JPY нельзя оплатить картой. Страница настроек показывает предупреждение, если валюта или учётные данные неверны. Также проверьте, что платёжный адрес входит в выбранную Geo Zone и что сумма заказа достигает значения Total, заданного в настройках.

The payment went through, but the order stays without a status: уведомление о результате не работает. В консоли магазина GMO-PG той среды, которую вы используете, проверьте, что 結果通知 включено и что URL в точности совпадает с указанным в Notification URL. Проверьте, что Shop ID и Shop password этой среды заполнены, так как расширение проверяет каждое уведомление с их помощью. Включите Debug log и посмотрите поле Log на странице расширения. Заказ также получит статус, когда покупатель вернётся в магазин после оплаты.

Log shows Notification rejected: unknown ShopID.: уведомление пришло от магазина, Shop ID которого нет в настройках. Введите Shop ID этой среды.

Log shows Notification ignored: OrderID is not a payment of this store.: транзакцию создал не этот магазин, например, её провели в консоли GMO-PG. Ничего делать не нужно.

Log shows that the order was paid in another environment: тестовые и рабочие платежи хранятся раздельно. Тестовое уведомление никогда не подтверждает рабочий платёж и наоборот.

The customer sees an error after Confirm Order: включите Debug log и посмотрите поле Log. Журнал показывает код ошибки GMO-PG (ErrCode, ErrInfo). Частая причина — неверный Shop ID, Shop password или Config ID. This payment method is not available at the moment. Please choose another payment method. означает, что сеанс оформления больше не соответствует заказу или способ оплаты был выключен в это время: покупатель должен перезагрузить страницу оформления.

Order is in the GMO-PG payment on hold status: прочитайте примечания на вкладке VibeFox GMO Payment Gateway. Заказ только авторизован и ждёт списания, или оплаченная сумма отличается от суммы заказа.

Refund or capture fails: прочитайте сообщение на вкладке. Заказ мог быть оплачен в другой среде, для которой не заданы Shop ID и пароль; транзакция может быть уже отменена в GMO-PG, либо сумма может превышать остаток по транзакции. The order is being updated by GMO-PG right now. Try again in a moment. означает, что в это же время обрабатывалось уведомление.

The tab shows You do not have permission to refund orders.: у вашей группы пользователей нет права на изменение расширения. Попросите администратора выдать его в System > Users > User Groups.

Удаление

Откройте Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox GMO Payment Gateway. Лицензионный ключ и статус лицензии этого расширения удаляются всегда. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и поля раздела Order statuses, которые при повторной установке возвращаются к значениям по умолчанию. На OpenCart 4 также удаляются событие расширения (сообщение оформления заказа) и его стартовое действие, которое пропускает уведомление и возврат покупателя в режиме обслуживания. Если Delete data on uninstall включено, удаляются остальные настройки шлюза (название, описание, среда, учётные данные, списание, статус заказа после оплаты, переключатель журнала отладки) и журнал. Если выключено, они сохраняются для повторной установки. Транзакции и возвраты GMO-PG сохраняются всегда, поэтому заказы, оплаченные раньше, можно списать и вернуть и после повторной установки. Существующие заказы сохраняют свои примечания об оплате.

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

GMO Payment Gateway — товарный знак его правообладателя. Это расширение не аффилировано с GMO Payment Gateway и не одобрено им.