VibeFox EveryPay for OpenCart — Помощь

Требования

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

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

Учётная запись EveryPay: вам нужны имя пользователя API, секрет API и название расчётного счёта (processing account) вашего интернет-магазина. Они показаны в EveryPay Merchant Portal, в настройках интернет-магазина. Демо-портал (тестовый режим) и боевой портал имеют разные учётные данные. Способы оплаты, которыми может пользоваться покупатель (карты, Apple Pay, Google Pay, банковские ссылки), — это те, которые включены для вашей учётной записи EveryPay.

Валюта: один расчётный счёт списывает только одну валюту. Название счёта начинается с кода его валюты, например EUR3D1 списывает в евро. EveryPay предлагается только тогда, когда покупатель платит в этой валюте.

Публичный сайт: URL callback вашего магазина должен быть доступен из интернета и не должен блокироваться базовой аутентификацией или файрволом.

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

Установка

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

OpenCart 3

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

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

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

4. Введите тестовое имя пользователя API, тестовый секрет API и название расчётного счёта из демо-портала. Скопируйте Callback notification URL в Merchant Portal (см. Настройка).

5. Включите Enable/Disable и нажмите Save. Оформите тестовый заказ в тестовом режиме, затем введите боевые учётные данные и выключите Test Mode.

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox EveryPay Payment > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница показывает Test mode is on: payments go to the EveryPay demo environment, no real money is charged., пока включён тестовый режим. Она предупреждает, если способ оплаты включён, но у текущего режима не заполнены имя пользователя API, секрет API или расчётный счёт (тогда способ оплаты скрыт на оформлении заказа), а также если валюта расчётного счёта отличается от валюты магазина по умолчанию. Без права изменять расширение страница показывает настройки, но не может их сохранить.

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

EveryPay

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely by card or bank link on the EveryPay payment page.

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

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

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

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

Имя пользователя API, секрет API и название расчётного счёта показаны в EveryPay Merchant Portal (настройки интернет-магазина): демо-портал для тестового режима и боевой портал для реальных платежей (в разделе есть ссылки на оба). Тестовая и боевая среды имеют разные учётные данные.

Test Mode: платежи уходят в демо-среду EveryPay с тестовыми учётными данными; реальные деньги не списываются. По умолчанию: включено. Выключите, чтобы принимать реальные платежи боевыми учётными данными. Пока режим включён, покупатель видит TEST MODE: EveryPay demo environment, no real money is charged. на шаге Confirm Order.

Test API Username: имя пользователя API демо-среды.

Test API Secret: секрет API демо-среды.

Live API Username: имя пользователя API боевой среды.

Live API Secret: секрет API боевой среды.

Processing Account Name: ваш расчётный счёт EveryPay, например EUR3D1. Счёт определяет списываемую валюту: способ оплаты предлагается только для заказов в этой валюте.

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

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

Callback сообщает вашему магазину, что платёж завершён, поэтому заказы подтверждаются, даже если покупатель закрыл браузер. Скопируйте URL, показанный в Callback notification URL, в поле callback-уведомлений вашего интернет-магазина в EveryPay Merchant Portal — и в демо-портале, и в боевом портале. В OpenCart 3 URL выглядит так: https://your-store/index.php?route=extension/payment/wcp_everypay_payment/callback, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_everypay_payment/payment/wcp_everypay_payment.callback. Он формируется из адреса витрины вашей установки OpenCart. Копируйте URL точно так, как он показан в настройках.

Callback содержит только ссылки на платежи. Расширение никогда не доверяет ему само по себе: оно запрашивает статус платежа у API EveryPay с учётными данными того режима, в котором был сделан платёж. Callback для платежа, который этот магазин не создавал, отклоняется без каких-либо запросов к EveryPay. Callback работает и тогда, когда магазин находится в режиме обслуживания, поскольку OpenCart 3 пропускает запросы платёжных расширений, а на OpenCart 4 расширение добавляет для этого стартовое действие (в том числе для возврата покупателя). Без callback заказ получит статус, когда покупатель вернётся в магазин или когда вы нажмёте Check EveryPay payment status на странице заказа.

Заказы

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

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

Manual Review Status: платёж был сделан, но сумма или валюта не совпадают с заказом, заказ был отменён в это время или использует другой способ оплаты. Примечание объясняет причину, и заказ не отмечается как оплаченный. По умолчанию: Ожидание, так как в OpenCart нет статуса On hold. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Cancelled Order Status: платёж, поступивший для заказа с этим статусом, передаётся на ручную проверку вместо оплаты заказа. По умолчанию: Отменён.

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию EveryPay). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to the secure EveryPay payment page. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способов оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Когда покупатель нажимает Confirm Order, расширение создаёт разовый платёж EveryPay на сумму заказа в валюте заказа, с адресом электронной почты покупателя и его платёжным адресом, и отправляет покупателя на страницу оплаты EveryPay. Язык страницы оплаты соответствует языку магазина покупателя (английский, эстонский, русский, латышский, литовский, финский или немецкий; иначе английский). Там покупатель платит одним из способов, включённых для вашей учётной записи EveryPay.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после того, как EveryPay его подтвердит: расширение запрашивает статус платежа у API EveryPay при возврате покупателя и по callback. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Если EveryPay ещё обрабатывает платёж или его API в этот момент недоступен, страница Payment confirmation показывает Your payment is being confirmed by EveryPay. You will receive an e-mail as soon as the order is confirmed. и кнопку Check again; callback установит статус заказа, как только EveryPay подтвердит платёж.

Если платёж не прошёл, покупатель возвращается на оформление заказа с сообщением Your EveryPay payment was not successful. Please try again or choose another payment method. Если покупатель покинул страницу оплаты, не заплатив, сообщение: The EveryPay payment was not completed. You can try again or choose another payment method. Корзина сохраняется, а заказ остаётся без статуса. На OpenCart 4 эти сообщения показываются над страницей оформления заказа.

OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; OpenCart 4 обновляет заказ при оформлении, поэтому новая попытка оплачивает тот же заказ новым платежом EveryPay. EveryPay не может отменить платёж после его создания. Поэтому перед новым платежом расширение проверяет через API EveryPay открытые попытки этого заказа и других заказов той же корзины. Если одна из них уже оплачена или другой заказ той же корзины уже оплачен, покупатель переходит на страницу успеха без второго платежа. Каждая попытка запоминается, поэтому платёж, сделанный по старой ссылке, всё равно распознаётся. Если покупатель всё же оплачивает второй заказ той же корзины (например, из двух открытых вкладок браузера), этот заказ не получает статус, покупатель видит страницу успеха заказа, а оплаченный заказ получает примечание с просьбой вернуть второй платёж в EveryPay Merchant Portal.

OpenCart 4 хранит заказ при оформлении до показа страницы успеха. Если за это время этот заказ был закрыт без оплаты (например, вы его отменили), покупатель возвращается к оформлению с сообщением Your previous order was cancelled. Please confirm the order again., а следующее нажатие Confirm Order оплачивает новый заказ корзины. Если этот заказ уже оплачен, но корзина с тех пор изменилась, в том числе количество, сообщение: Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. Оплаченный заказ никогда не показывается оплаченным для другой корзины.

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

Расширение принимает только разовые платежи. В нём нет возвратов и списаний (capture) из магазина, сохранённых карт и платежей в один клик, подписок и регулярных платежей, встроенных полей карты и мультивалютности.

Заказы

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

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

Order Status After Payment (default Processing): EveryPay сообщил, что платёж списан или авторизован. Примечание показывает сумму, валюту и ссылку на платёж. Для авторизованного платежа примечание сообщает, что средства зарезервированы: если ваш счёт не списывает автоматически, выполните списание (capture) платежа в EveryPay Merchant Portal. Когда платёж позже будет расчётным, одно примечание сообщит об этом.

Manual Review Status (default Pending): платёж требует ручной проверки. Оплаченная сумма или валюта не совпадают с заказом, заказ имел Cancelled Order Status до поступления платежа, или заказ сейчас использует другой способ оплаты. Примечание объясняет это и сообщает, что заказ не был отмечен как оплаченный. Проверьте платёж в Merchant Portal и вручную выполните заказ или сделайте возврат. Последующие callback по этому платежу не завершают заказ автоматически; правильный платёж по другой попытке того же заказа всё же его оплачивает.

Если второй платёж завершён по уже оплаченному заказу, заказ не меняется. Примечание просит вас вернуть дублирующий платёж в EveryPay Merchant Portal. Примечания — это записи в History заказа, которые покупатель не видит.

Вкладка VibeFox EveryPay Payment

В Sales > Orders откройте заказ, оплаченный через EveryPay. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox EveryPay Payment показывает EveryPay payments of this order: Payment reference, Order reference, Mode (тестовый или боевой), Amount, EveryPay state, Result и Date каждой попытки. Ниже находятся EveryPay notes заказа. Вкладка показывается пользователям, имеющим доступ к расширению.

Check EveryPay payment status: кнопка на вкладке запрашивает через API статус каждого платежа EveryPay по заказу, от новых к старым, с учётными данными его режима, применяет результат, как описано выше, и добавляет одно примечание со статусом каждого платежа. Затем вкладка перезагружается. Нужно право изменять заказы (System > Users > User Groups); право изменять расширение не требуется. Используйте кнопку, когда callback не пришёл, например чтобы увидеть более позднее списание или возврат. Статус, установленный этой кнопкой, записывается как ручное изменение статуса в админке, без писем о заказе и обновления остатков, как при оформлении заказа.

Возвраты

Возвраты и списания (capture) из магазина не поддерживаются. Выполните возврат в EveryPay Merchant Portal, затем обновите статус заказа в OpenCart. Когда EveryPay сообщает, что платёж возвращён или оспорен (chargeback), расширение только добавляет примечание к заказу; статус заказа не меняется. Возвраты товаров в Sales > Returns не возвращают деньги через EveryPay.

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

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

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

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

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

EveryPay does not appear at checkout: проверьте, что лицензия активна, Enable/Disable включён, имя пользователя API, секрет API и Processing Account Name текущего режима заполнены, и покупатель платит в валюте расчётного счёта. В этих случаях страница настроек показывает предупреждение. Также проверьте, что платёжный адрес входит в выбранную Geo Zone и что заказ достигает Total, заданного в настройках.

The payment went through, but the order stays without a status: callback не работает. Проверьте, что URL из Callback notification URL указан в Merchant Portal того режима, который вы используете (демо или боевой), и что он открывается из интернета. Заказ также получит статус, когда покупатель вернётся в магазин после оплаты. Посмотрите поле Log на странице расширения: ошибки всегда записываются.

Callback answers Unknown payment, Unknown payment reference, Payment cannot be verified or Payment does not belong to this order: платёж создан не этим магазином или не для этого заказа, либо ответ EveryPay не соответствует ему. Ничего не меняется.

Callback answers Missing or invalid payment_reference: запрос не содержал корректной ссылки на платёж, например когда URL открыт в браузере.

Callback answers Not configured: отсутствуют учётные данные среды, в которой был создан платёж, например тестовый платёж после удаления тестовых учётных данных. Введите их снова; EveryPay повторит callback.

Callback answers Payment status unavailable, Busy, please retry or Processing error, please retry: API EveryPay было не получить, заказ в тот же момент обрабатывал другой запрос, или обработка не удалась. Причина указана в журнале. EveryPay повторит callback.

The customer sees This payment method is not available right now: отсутствуют учётные данные или расчётный счёт текущего режима.

The customer sees EveryPay is temporarily unavailable or Unable to start the EveryPay payment: EveryPay отклонил учётные данные или не был доступен. Проверьте имя пользователя и секрет API текущего режима.

The customer sees This payment method does not support the order currency: валюта заказа отличается от валюты расчётного счёта.

The customer stays on the Payment confirmation page: EveryPay ещё не завершил платёж. Заказ получит статус по callback или когда покупатель нажмёт Check again после того, как EveryPay подтвердит платёж.

Order is in the review status: прочитайте EveryPay notes на вкладке VibeFox EveryPay Payment. Сумма или валюта не совпали, заказ был отменён до поступления платежа, или он использует другой способ оплаты. Проверьте платёж в Merchant Portal и вручную выполните заказ или сделайте возврат.

Для разработчиков: перед созданием платежа расширение вызывает события OpenCart wc_evp_oneoff_request (изменить запрос платежа) и wc_evp_locale (изменить язык страницы оплаты).

Удаление

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

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

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