VibeFox eWAY for OpenCart — Помощь

Требования

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

PHP: 8.0 или новее, с расширением cURL.

Валюта: AUD, NZD, SGD, HKD или MYR. Для других валют оформления заказа способ оплаты скрыт на оформлении. Оплата списывается в валюте заказа.

Учётная запись eWAY: нужна учётная запись мерчанта eWAY с доступом к Rapid API и её ключ и пароль Rapid API; их можно найти в MyeWAY в разделе Settings, API Key. Для тестирования нужна песочница eWAY (sandbox) со своим ключом и паролем. Ключи песочницы и боевые ключи различаются. В MyeWAY ничего настраивать не нужно: URL возврата передаётся с каждым платежом.

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

Установка

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

OpenCart 3

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

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

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

4. Введите ключ и пароль API песочницы, оставьте Sandbox Mode включённым, включите Enable/Disable, нажмите Save и оформите тестовый заказ.

5. Введите боевой ключ и пароль API, выключите Sandbox Mode и нажмите Save.

6. По желанию добавьте URL cron, показанный на странице настроек, в задания cron вашего сервера (см. Настройка).

OpenCart 4

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

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

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

4. Введите лицензионный ключ, ключи eWAY и URL cron, как в шагах 3–6 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только URL cron (см. Re-check of lost returns (cron)).

Новая установка начинает работу с выключенным способом оплаты и включённым режимом песочницы.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox eWAY Payment Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками бейдж показывает режим: SANDBOX — payments go to the eWAY sandbox, no real money is charged. или LIVE — real payments are taken with the live API key. Страница предупреждает, если не заполнены ключ или пароль API текущего режима (тогда способ оплаты не показывается на оформлении заказа), и если eWAY не поддерживает валюту магазина по умолчанию. Без права изменять расширение страница показывает настройки, но не может их сохранить.

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

eWAY

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

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

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

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

Учётные данные API

Ключ и пароль Rapid API находятся в MyeWAY в разделе Settings, API Key. eWAY публикует инструкции для боевых ключей и ключей песочницы; ссылки на них есть в этом разделе. Ключи песочницы и боевые ключи различаются. Режим песочницы использует только учётные данные песочницы, боевой режим — только боевые учётные данные.

Sandbox Mode: платежи уходят в песочницу eWAY с ключом и паролем песочницы; реальные деньги не списываются. По умолчанию: включено. Выключите, чтобы принимать боевые платежи с боевым ключом. Пока режим включён, покупатель видит Test mode: no real payment is taken. на шаге Confirm Order.

Live API Key: ключ Rapid API вашей боевой учётной записи eWAY.

Live API Password: пароль Rapid API вашей боевой учётной записи eWAY.

Sandbox API Key: ключ Rapid API вашей учётной записи песочницы eWAY (партнёрской или разработческой).

Sandbox API Password: пароль Rapid API вашей учётной записи песочницы eWAY.

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

Return URL: показывает адрес возврата расширения. Он автоматически передаётся в eWAY с каждым платежом вместе с заказом и случайным ключом попытки оплаты, поэтому в MyeWAY ничего настраивать не нужно. Результат платежа всегда запрашивается у eWAY с сервера на сервер.

Re-check of lost returns (cron): необязательный URL cron, показанный под URL возврата. Вызывайте его из задания cron вашего сервера каждые 15 минут, например с помощью curl. Если покупатель оплатил и закрыл браузер, не вернувшись в магазин, платёж запрашивается у eWAY примерно через 60 минут после отправки покупателя в eWAY, и заказ обновляется. Если eWAY недоступен, проверка повторяется до трёх раз. Храните этот URL в секрете: он содержит секретный токен, созданный при установке, а вызов с неверным токеном получает ответ Forbidden. В OpenCart 4 URL выглядит так: https://your-store/index.php?route=extension/wcp_eway_payment_gateway/payment/wcp_eway_payment_gateway.cron&token=(token).

Заказы

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

Order Status on Success: статус, который устанавливается, когда eWAY подтверждает платёж. По умолчанию: В обработке.

eWAY payment on hold status: статус для одобренного платежа, который требует вашей проверки: сумма или валюта не совпадают с заказом, платёж одобрен после того, как покупатель нажал Cancel на странице eWAY, или заказ уже имел другой статус. Примечание в истории заказа объясняет причину. По умолчанию: Ожидание, так как в OpenCart нет статуса On hold. Собственный статус можно создать в System > Localisation > Order Statuses и выбрать его здесь.

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

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

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

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

Delete all extension data on uninstall: если включено, при удалении расширения удаляются настройки шлюза и журнал. Записи о платежах и возвратах eWAY по заказам всегда сохраняются. По умолчанию: выключено.

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Credit Card (eWAY)). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to the secure eWAY payment page to pay by card. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Когда покупатель нажимает Confirm Order, расширение запрашивает у eWAY страницу оплаты на сумму заказа в валюте заказа, с OC- и номером заказа в качестве счётного (invoice) номера, а также с платёжным адресом и адресом электронной почты покупателя, и отправляет покупателя на защищённую страницу eWAY (Responsive Shared Page). Там покупатель платит картой. Списание выполняется сразу.

После оплаты покупатель возвращается в ваш магазин. Расширение не доверяет браузеру: оно запрашивает у eWAY с сервера на сервер результат страницы оплаты, созданной для этого заказа. Заказ отмечается оплаченным только после того, как eWAY подтвердит платёж и одобренные сумма и валюта совпадут с заказом. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Для заказа на удержании страница дополнительно показывает Your payment was received and is being reviewed by the store. We will contact you if anything is needed.

Если в этот момент запросить eWAY невозможно, страница Payment confirmation показывает We have not received the confirmation of your payment from eWAY yet. If you completed the payment, this order will be updated shortly — please do not pay again. с кнопкой Check again и кнопкой Back to checkout. Заказ получит статус, когда покупатель проверит снова или когда будет вызван URL cron.

Если платёж отклонён, покупатель возвращается на оформление заказа с причиной, например Your payment was declined: D4451 Insufficient funds. Please try again or use a different payment method. Заказ остаётся без статуса. Если покупатель нажимает Cancel на странице eWAY, расширение сначала проверяет у eWAY, что ничего не оплачено (например, в другой вкладке). Затем покупатель видит You cancelled the payment on the eWAY page. Your order has not been paid — you can try again. Если платёж не был завершён, сообщение: The payment was not completed. Please try again. Корзина во всех случаях сохраняется. В OpenCart 4 эти сообщения показываются над страницей оформления заказа.

Покупатель может попробовать снова. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, а OpenCart 4 обновляет текущий заказ оформления, поэтому новая попытка открывает новую страницу оплаты eWAY для того же заказа. Перед созданием новой страницы оплаты предыдущие страницы этого заказа и других заказов той же корзины проверяются в eWAY. Если какая-либо из них уже оплачена, подтверждается именно этот платёж, а не создаётся второй. Если eWAY не может ответить по ним, покупатель видит We could not check the status of your previous payment attempt. Please try again in a moment. Если eWAY не может создать страницу оплаты, покупатель остаётся на шаге Confirm Order с коротким сообщением, например Payment error: Unable to connect to eWAY. Please try again. или eWAY could not start the payment с кодами ошибок eWAY.

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

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

eWAY не отправляет уведомления с сервера на сервер для Shared Page: результат получается, когда покупатель возвращается, и через URL cron. В расширении нет полей карты на вашем сайте, нет сохранённых карт и подписок, нет авторизации без списания и последующего списания (capture), а оценки мошенничества Beagle не анализируются (транзакции, заблокированные правилами eWAY против мошенничества, отклоняются самим eWAY).

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

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

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

Order Status on Success (default Processing): платёж одобрен. Примечание показывает ID транзакции eWAY, код авторизации, ответ и режим (песочница или боевой).

eWAY payment on hold status (default Pending): eWAY одобрил сумму или валюту, отличную от заказа (например, Approved for partial amount), платёж был одобрен после того, как покупатель отменил его на странице eWAY, или он одобрен для заказа, которому вы уже присвоили статус, например Отменён. Фактически списанная eWAY сумма записывается, и примечание это объясняет. Проверьте заказ и выполните его либо сделайте возврат платежа.

Refunded order status (default Refunded): платёж полностью возвращён через расширение.

Если второй платёж одобрен для уже оплаченного заказа или для другого заказа той же корзины, оплаченный заказ не меняется. Примечание просит вас вернуть дубликат в MyeWAY. Одобренный платёж с другой счётной ссылкой (invoice reference) никогда не применяется к заказу.

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

Вкладка VibeFox eWAY Payment Gateway

В Sales > Orders откройте заказ, оплаченный через eWAY. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox eWAY Payment Gateway показывает ID eWAY transaction с меткой Sandbox или Live, Auth code, Response eWAY, Invoice reference, Status платежа, суммы Paid / refunded, форму возврата, историю возвратов и eWAY notes заказа. Вкладка показывается пользователям, имеющим доступ к расширению.

Возвраты

На вкладке введите сумму (ещё не возвращённая сумма подставляется автоматически), при желании Reason (optional), и нажмите Refund via eWAY. Подтвердите вопрос Refund this amount through eWAY? This cannot be undone. Поддерживаются полные и частичные возвраты. Нужно право изменять расширение (настраивается в System > Users > User Groups). Возвраты выполняются в той сумме и валюте, которые списал eWAY, поэтому после одобрения на частичную сумму можно вернуть не больше того, что покупатель фактически оплатил, а не сумму заказа. Возврат отправляется в той среде, где был сделан платёж (песочница или боевая), поэтому должны быть заполнены ключ и пароль API этой среды. Если eWAY отклоняет возврат, вкладка показывает eWAY refund failed: с кодами eWAY, и возврат не записывается. Успешный возврат добавляется в историю возвратов и в примечания с ID транзакции возврата eWAY. Полный возврат устанавливает заказу статус Refunded order status без уведомления покупателя и без возврата товаров на склад, как при ручном изменении статуса. Частичный возврат статус не меняет. Возвраты доступны после того, как eWAY одобрил платёж.

Возвраты товаров в Sales > Returns не возвращают деньги через eWAY. Возвраты, сделанные в MyeWAY, не синхронизируются обратно с OpenCart. При необходимости обновите заказ вручную.

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

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

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

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

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

eWAY does not appear at checkout: проверьте, что лицензия активна, Enable/Disable включён, заполнены ключ и пароль API текущего режима (поля песочницы в режиме песочницы, боевые поля в боевом режиме), а валюта оформления заказа — AUD, NZD, SGD, HKD или MYR. Страница настроек показывает предупреждение, если учётные данные не заполнены. Также проверьте, что платёжный адрес входит в выбранную Geo Zone и что заказ достигает Total, заданного в настройках.

The payment went through, but the order stays without a status: покупатель не вернулся из eWAY, или в этот момент не удалось запросить eWAY. eWAY не отправляет уведомлений для Shared Page. Настройте URL cron из раздела Re-check of lost returns (cron): он подхватит платёж примерно через час. Проверьте транзакцию в MyeWAY и посмотрите поле Log на странице расширения.

The cron URL answers Forbidden: токен в URL неверный. Скопируйте URL точно так, как он показан на странице настроек.

The customer sees This payment method is temporarily unavailable: ключ или пароль API текущего режима отсутствуют, либо eWAY их отклонил. Проверьте учётные данные текущего режима.

The customer sees eWAY could not start the payment: eWAY вернул коды ошибок, которые показаны в сообщении. Часто причина в некорректных платёжных данных.

The customer sees eWAY cannot take payments in a currency: валюта заказа не входит в число валют, которые принимает eWAY. Используйте AUD, NZD, SGD, HKD или MYR.

The customer sees We could not match this payment to an order: ссылка возврата не относится к заказу этого магазина, либо eWAY одобрил платёж для другой счётной ссылки (invoice reference). Если с покупателя списаны деньги, найдите платёж в MyeWAY.

The customer sees This payment method is not available: сессия оформления заказа больше не соответствует заказу, либо способ оплаты тем временем был выключен. Покупатель перезагружает оформление заказа.

Order is in the on hold status after payment: прочитайте eWAY notes на вкладке VibeFox eWAY Payment Gateway (см. Статусы заказов), затем выполните заказ или сделайте возврат платежа.

No refund form in the tab: вкладка показывает причину: для заказа не найден ID транзакции eWAY, заказ полностью возвращён, ваша группа пользователей не имеет права изменять расширение, либо не заполнены учётные данные API того режима, в котором прошёл платёж.

Refund fails with a message about the sandbox or live mode: заказ оплачен в этой среде, а её ключ и пароль API не заполнены. Введите их и повторите попытку.

Refund fails with at most … can be refunded: сумма больше того, что eWAY списал, за вычетом уже выполненных возвратов.

Для разработчиков: расширение вызывает события OpenCart wcp_eway_payment_gateway_supported_currencies (если ваша учётная запись eWAY подключена к другим валютам) и wcp_eway_payment_gateway_create_access_code_request (тело запроса перед созданием страницы оплаты).

Удаление

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

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

eWAY — торговая марка её владельца. Это расширение не связано с eWAY и не одобрено eWAY.