VibeFox ifthenpay for OpenCart — Помощь

Требования

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

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

Валюта: только евро (EUR). Валюта EUR должна быть включена в вашем магазине, а способ оплаты показывается только тогда, когда покупатель платит в EUR. ifthenpay принимает суммы от 0,01 до 99 999,99 EUR.

Учётная запись ifthenpay: зарегистрируйтесь на ifthenpay.com. Вам нужен ключ того способа оплаты, который вы предлагаете: Multibanco, MB WAY или Credit Card (формат ABC-123456). Ключи показаны в личном кабинете ifthenpay (backoffice.ifthenpay.com) или присылаются ifthenpay при активации способа оплаты для вашей учётной записи. ifthenpay также должна активировать callback для вашего ключа (см. Настройка), а ваш магазин должен быть доступен из интернета.

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

Установка

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

OpenCart 3

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

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

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

4. Выберите Payment Method, введите его ключ ifthenpay и нажмите Save, чтобы Callback URL соответствовал выбранному способу.

5. Скопируйте Anti-phishing Key и Callback URL из раздела Callback и попросите ifthenpay активировать callback для вашего ключа (в личном кабинете или через поддержку ifthenpay).

6. Включите Enable/Disable и нажмите Save.

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox ifthenpay Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Без ключа выбранного способа оплаты он не показывается на оформлении заказа. Пока шлюз включён без этого ключа, страница показывает ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

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

ifthenpay

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay via Multibanco, MB WAY or Credit Card. Измените его в соответствии со способом оплаты, который вы предлагаете.

Payment Method: способ оплаты, который предлагается на оформлении заказа. Требуется только ключ этого способа.

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

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

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

Ключи ifthenpay

Ключи (формат ABC-123456) показаны в личном кабинете ifthenpay (в этом разделе есть ссылка на него) или присылаются ifthenpay при активации способа оплаты для вашей учётной записи.

Multibanco Key: ваш ключ ifthenpay Multibanco (MB) для динамических референсов.

MB WAY Key: ваш ключ ifthenpay MB WAY.

Credit Card Key: ваш ключ ifthenpay Credit Card. Он также проверяет подпись возврата покупателя со страницы карты.

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

Callback

Callback сообщает вашему магазину, что платёж произведён. Попросите ifthenpay активировать callback для каждого используемого ключа, указав anti-phishing ключ и Callback URL из этого раздела. Заказы Multibanco и MB WAY подтверждаются только callback; платежи картой подтверждаются также подписанным возвратом со страницы карты.

Anti-phishing Key: создаётся расширением и показывается для копирования. ifthenpay присылает его обратно в каждом callback; callback без него отклоняются.

Callback URL: Callback URL для выбранного способа оплаты с плейсхолдерами ifthenpay, показывается для копирования. В OpenCart 3 он начинается с https://your-store/index.php?route=extension/payment/wcp_ifthenpay_gateway/callback, в OpenCart 4 — с https://your-store/index.php?route=extension/wcp_ifthenpay_gateway/payment/wcp_ifthenpay_gateway.callback. Он формируется из адреса витрины вашей установки OpenCart и продолжается параметрами способа оплаты. Копируйте URL полностью, точно так, как его показывают настройки. Если вы меняете Payment Method, сохраните настройки и скопируйте новый URL.

Anti-phishing ключ в каждом callback сравнивается с вашим. Отсутствующий или неверный ключ получает ответ 403, и заказ не меняется. Callback также должен соответствовать платежу этого расширения: для Multibanco — по сущности и референсу, для MB WAY — по заказу и одному из его запросов MB WAY, для Credit Card — по заказу и одному из его запросов карты. Без работающего callback заказы Multibanco и MB WAY никогда не подтверждаются, а платежи картой подтверждаются только подписанным возвратом. Callback также работает, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы платёжных расширений, а в OpenCart 4 расширение добавляет стартовое действие, которое пропускает callback и возврат покупателя со страницы карты.

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Для Multibanco и MB WAY заказ получает статус ожидания, как только ifthenpay выдала референс или отправила запрос MB WAY; для Credit Card заказ получает статус только по callback или подписанному возврату. Заказ отмечается оплаченным только тогда, когда сумма совпадает с суммой заказа до копейки. Каждое из полей ниже перечисляет ваши статусы заказов OpenCart.

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

Awaiting payment status: выдан референс Multibanco или отправлен запрос MB WAY, и покупатель ещё должен оплатить. Реквизиты Multibanco отправляются с этим статусом — в письме о заказе и в истории заказов покупателя. По умолчанию: Ожидание.

Payment on hold status: ifthenpay сообщила о платеже, который не соответствует заказу (сумма, валюта), о платеже после отмены заказа или о платеже по заказу, корзина которого уже была оплачена. Примечание объясняет причину. По умолчанию: Ожидание, поскольку в OpenCart нет статуса On hold. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

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

Test Mode: Credit Card и Multibanco используют тестовые (sandbox) адреса ifthenpay; реальные деньги не списываются, и вы используете тестовые ключи, которые предоставляет ifthenpay. У MB WAY нет sandbox: тестируйте его тестовым ключом ifthenpay. На шаге Confirm Order показывается значок TEST MODE. По умолчанию: выключено.

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

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

Delete Data on Uninstall: если включено, при удалении расширения удаляются настройки шлюза, anti-phishing ключ и журнал. Заказы и записи платежей ifthenpay всегда сохраняются. По умолчанию: выключено.

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию ifthenpay). На шаге Confirm Order покупатель видит ваше описание и подсказку по способу оплаты. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса.

В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа.

Multibanco. Покупатель видит You will receive a Multibanco reference to complete the payment. Когда покупатель нажимает Confirm Order, расширение создаёт динамический референс Multibanco на сумму заказа, и заказ получает Awaiting payment status. На странице успешного оформления заказа показывается Multibanco Payment Details: сущность, референс и сумма, с текстом Please use these details to pay at any Multibanco ATM or through your online banking. Те же данные отправляются в письме о заказе и отображаются в истории заказов покупателя. Если для заказа уже выдан референс на ту же сумму, он повторно используется. Заказ оплачивается, когда ifthenpay присылает callback о платеже.

MB WAY. Покупатель вводит MB WAY phone number (912 345 678, +351 912 345 678 или 351#912345678 для других стран); телефон из заказа подставляется автоматически. Расширение отправляет запрос на оплату на телефон, и заказ получает Awaiting payment status. На странице успешного оформления заказа написано A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. Заказ оплачивается, когда ifthenpay присылает callback. Сохраняется только замаскированный номер телефона. По умолчанию OpenCart 4 не запрашивает телефон на оформлении заказа; поле остаётся пустым, и покупатель вводит номер.

Credit Card. Покупатель видит You will be redirected to a secure page to enter your card details. и перенаправляется на страницу карты ifthenpay. Заказ остаётся без статуса, корзина сохраняется. После успешного платежа покупатель возвращается в ваш магазин. Возврат принимается только при действительной подписи ifthenpay, секрете этой попытки и запросе карты по заказу; тогда заказ отмечается оплаченным, и покупатель видит страницу успешного оформления заказа OpenCart. Если возврат не удаётся проверить, ничего не меняется, а страница Payment confirmation показывает Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. с кнопками Check again и Back to checkout; callback подтверждает платёж, как только приходит. Если платёж картой не прошёл или отменён, покупатель возвращается к оформлению заказа с сообщением The card payment was not completed. You can try again or choose another payment method. или The card payment was cancelled. You can try again or choose another payment method. Каждая попытка оплаты картой по заказу сохраняется, поэтому платёж, сделанный во вкладке, открытой ранее, тоже принимается. В OpenCart 4 эти сообщения показываются над страницей оформления заказа.

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

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

Если платёж не удаётся начать, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, например The Multibanco reference could not be created. Please try again or choose another payment method., The MB WAY payment request could not be sent. Please check that the phone number is linked to MB WAY, or choose another payment method. или The payment service is temporarily unavailable. Please try again in a few minutes. Техническая причина записывается в лог.

Расширение предлагает один способ ifthenpay за раз. Оно не поддерживает Payshop, Cofidis Pay, Apple Pay, Google Pay, PIX или Pay-by-Link, подписки или сохранённые карты, автоматическое истечение или отмену неоплаченных референсов Multibanco, а также опрос статуса платежа.

Заказы

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

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

Awaiting payment status (default Pending): выдан референс Multibanco или отправлен запрос MB WAY. Неоплаченные референсы и отклонённые запросы MB WAY не отменяют заказ автоматически; при необходимости отмените такие заказы сами.

Order Status After Payment (default Processing): платёж подтверждён. Примечание показывает референс Multibanco, транзакцию MB WAY или ID запроса карты, а также способ подтверждения.

Payment on hold status (default Pending): полученная сумма отличалась от суммы заказа (например, корзину изменили после начала платежа картой), платёж поступил после отмены заказа или другой заказ той же корзины уже был оплачен. Примечание объясняет это, и покупателя не просят платить повторно. Проверьте платёж в личном кабинете ifthenpay и вручную завершите или возвратите заказ. Более поздний корректный платёж по такому заказу его не меняет.

Второй платёж по уже оплаченному заказу только добавляет примечание — проверить возможный дубликат платежа в личном кабинете ifthenpay. Заказ, который вы перевели в другой статус (например, возврат), никогда не открывается снова; вместо этого добавляется примечание.

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

Вкладка VibeFox ifthenpay Gateway

В Sales > Orders откройте заказ, оплаченный через ifthenpay. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox ifthenpay Gateway перечисляет попытки оплаты по заказу (дата, способ, метка Sandbox для тестовых платежей, сумма, сущность и референс Multibanco или замаскированный телефон MB WAY, ID запроса ifthenpay и статус), предупреждение Payment on hold, пока заказ находится на удержании, и ifthenpay notes заказа. Вкладка доступна только для чтения и показывается пользователям, которые имеют доступ к расширению.

Возвраты

Возвраты из OpenCart не поддерживаются. Выполните возврат платежа в личном кабинете ifthenpay и вручную зафиксируйте его в OpenCart. Возвраты товаров в Sales > Returns не возвращают деньги через ifthenpay. Callback о возврате (DEVOLVIDO) только добавляет примечание. Другие статусы, которые сообщает ifthenpay, тоже только добавляют примечание.

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

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

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

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

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

ifthenpay не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, ключ выбранного Payment Method заполнен, покупатель платит в EUR, а сумма составляет от 0,01 до 99 999,99 EUR. Также проверьте, что платёжный адрес входит в выбранную Geo Zone, и что сумма заказа достигает значения Total из настроек.

Покупатель заплатил, но заказ остаётся в статусе ожидания или без статуса: callback не доходит до вашего магазина. Проверьте, что ifthenpay активировала Callback URL и anti-phishing ключ для используемого ключа, и что URL соответствует выбранному способу. Магазин должен быть доступен из интернета, а не на localhost и не за логином. Включите Debug Log и посмотрите поле Log на странице расширения.

Callback отвечает 403 Forbidden: anti-phishing ключ в callback отсутствует или отличается от указанного в настройках. Отправьте ifthenpay ключ, который показан в настройках, ещё раз.

Callback отвечает 503 Not configured: anti-phishing ключ ещё не создан. Откройте настройки расширения один раз; ifthenpay повторит callback.

Callback отвечает 503 Busy: в этот момент тот же заказ обрабатывал другой запрос. ifthenpay повторит callback.

Callback отвечает Order not found: референс или запрос не относится к платежу этого расширения, или заказ был оформлен с другим способом оплаты.

Почему оплаченный заказ перевели на удержание? Полученная сумма отличалась от суммы заказа, платёж поступил после отмены заказа, или другой заказ той же корзины уже был оплачен. Прочитайте примечания на вкладке VibeFox ifthenpay Gateway, проверьте платёж в личном кабинете ifthenpay и вручную завершите или возвратите заказ.

Запрос MB WAY не удалось отправить: номер телефона не привязан к MB WAY или имеет неверный формат. Используйте 912 345 678 или 351#912345678 для номеров других стран.

Тестовый режим и MB WAY: у ifthenpay нет sandbox для MB WAY; используйте тестовый ключ, предоставленный ifthenpay.

Удаление

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

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

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