VibeFox ifthenpay for PrestaShop — Помощь
Требования
PrestaShop: 8.0 – 9.x.
PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.
Валюта: только евро (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. Один ключ работает на одном домене.
Установка
1. В бэк-офисе перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.
2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox ifthenpay Gateway в списке модулей и нажмите Configure. Модуль создаёт антифишинговый ключ при установке.
3. Введите лицензионный ключ VibeFox в поле License key блока лицензии вверху страницы Configure и нажмите Activate (см. Лицензионный ключ).
4. Выберите Payment Method, введите его ключ ifthenpay и нажмите Save, чтобы Callback URL соответствовал выбранному способу.
5. Скопируйте Anti-phishing Key и Callback URL, показанные в настройках, и попросите ifthenpay активировать callback для вашего ключа (в бэк-офисе или через поддержку ifthenpay).
6. Включите Enable/Disable и нажмите Save.
При установке модуль создаёт два статуса заказа: Awaiting ifthenpay payment и ifthenpay payment on hold. PrestaShop включает новый платёжный модуль для всех валют, стран и групп клиентов. Ограничить их можно в Payment > Preferences; EUR должен оставаться разрешённым.
Настройки
Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox ifthenpay Gateway > Configure. Каждый раздел с кнопкой Save сохраняет всю страницу. Без ключа выбранного способа платёжный способ не показывается при оформлении заказа. Пока шлюз включён без этого ключа, страница показывает ifthenpay: enter the key of the selected payment method, otherwise the method is not shown at checkout.
ifthenpay
Enable/Disable: Enable ifthenpay Payment включает или выключает платёжный способ. По умолчанию: off.
Title: название платёжного способа, которое показывается при оформлении заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: ifthenpay.
Description: описание платёжного способа, которое показывается при оформлении заказа. По умолчанию: Pay via Multibanco, MB WAY or Credit Card. Измените его под способ, который вы предлагаете.
Payment Method: способ, который предлагается при оформлении заказа. Обязателен только ключ этого способа.
Ключи 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 saved keys: отметьте ключ и нажмите Save, чтобы удалить его. Пустое поле оставляет сохранённое значение.
Callback (уведомления об оплате)
Callback сообщает вашему магазину, что оплата произведена. Попросите ifthenpay активировать callback для каждого используемого ключа, указав антифишинговый ключ и callback URL, приведённые ниже. Заказы Multibanco и MB WAY подтверждаются только callback; платежи картой дополнительно подтверждаются подписанным возвратом со страницы карт.
Anti-phishing Key: создаётся модулем и показывается для копирования. ifthenpay возвращает его в каждом callback; callback без него отклоняются.
Callback URL: callback URL для выбранного платёжного способа с плейсхолдерами ifthenpay, показан для копирования. При ЧПУ-адресах он начинается так: https://your-shop/module/wcp_ifthenpay_gateway/callback, возможно с кодом языка, например /en/, и продолжается параметрами способа. Скопируйте URL целиком, точно так, как он показан в настройках.
Антифишинговый ключ в каждом callback сравнивается с вашим. Отсутствующий или неверный ключ получает ответ 403, и заказ не меняется. Callback также должен соответствовать платежу этого модуля: для Multibanco — по организации (entity) и референсу, для MB WAY — по корзине и одному из её запросов MB WAY, для Credit Card — по корзине и одному из её запросов по карте. Без рабочего callback заказы Multibanco и MB WAY никогда не подтверждаются, а платежи картой подтверждаются только подписанным возвратом. Callback работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.
Дополнительно
Test Mode: Credit Card и Multibanco используют песочницу ifthenpay; реальные деньги не списываются, вы используете тестовые ключи, которые предоставляет ifthenpay. У MB WAY нет песочницы: проверяйте его с тестовым ключом от ifthenpay. На оформлении заказа показывается значок TEST MODE. По умолчанию: off.
Order Status After Payment: статус заказа, который присваивается после подтверждённой оплаты, с одним изменением статуса.
Debug Log: запросы к API и callback записываются в logs/ifthenpay_p_debug.log.php в папке модуля. Файл нельзя открыть из веба. Ошибки записываются всегда. Ключи, антифишинговый ключ и полные номера телефонов никогда не записываются в журнал. По умолчанию: off.
Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.
Delete Data on Uninstall: если включено, при удалении модуля удаляются его настройки, антифишинговый ключ и журнал. Заказы и записи платежей ifthenpay всегда сохраняются. По умолчанию: off.
Оформление заказа
Multibanco. При оформлении заказа покупатель видит You will receive a Multibanco reference to complete the payment. Когда покупатель подтверждает заказ, модуль создаёт динамический референс Multibanco на сумму корзины, и заказ создаётся в статусе Awaiting ifthenpay payment. На странице подтверждения заказа показывается Multibanco Payment Details: организация (entity), референс и сумма, с текстом 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 ifthenpay payment. На странице подтверждения заказа написано: A payment request has been sent to your phone via MB WAY. Please confirm it in the MB WAY app. Заказ оплачивается, когда ifthenpay присылает callback. Сохраняется только замаскированный номер телефона.
Банковская карта. Покупатель видит You will be redirected to a secure page to enter your card details. и перенаправляется на страницу карт ifthenpay. Заказа ещё нет, корзина сохраняется. После успешной оплаты покупатель возвращается в ваш магазин. Возврат принимается только при действительной подписи ifthenpay, защищённом ключе корзины, секрете этой попытки и запросе по карте для корзины; тогда заказ создаётся как оплаченный, и покупатель видит стандартную страницу подтверждения заказа. Если возврат не удаётся проверить, ничего не меняется, и страница Payment confirmation показывает Your card payment is being confirmed by ifthenpay. You will receive an e-mail as soon as it is confirmed. с кнопкой Check again; 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. Каждая попытка оплаты картой для корзины сохраняется, поэтому платёж, сделанный во вкладке, открытой раньше, всё равно принимается.
Заказ помечается оплаченным, только когда ifthenpay подтверждает оплату, а сумма проверяется до копейки по сумме заказа. Если оплату не удаётся начать, покупатель остаётся на оформлении заказа с коротким сообщением, например 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 order yet: платёж картой начат и ещё не подтверждён, либо он не прошёл или был отменён. Существует только корзина.
Awaiting ifthenpay payment: выпущен референс Multibanco или отправлен запрос MB WAY. PrestaShop уменьшает остаток товара при создании заказа. Неоплаченные референсы и отклонённые запросы MB WAY не отменяют заказ автоматически; при необходимости отмените такие заказы сами.
Payment accepted or Delivered: оплата подтверждена. Статус соответствует Order Status After Payment. Платёж записывается с референсом Multibanco, ID запроса MB WAY или ID запроса по карте в качестве ID транзакции, а примечание показывает, как он был подтверждён.
ifthenpay payment on hold: полученная сумма отличалась от суммы заказа (например, корзина была изменена после начала платежа картой), либо платёж пришёл после отмены заказа. Примечание объясняет это, и покупателя не просят платить повторно. Проверьте платёж в бэк-офисе ifthenpay и вручную завершите или возвратите заказ. Последующий правильный платёж по такому заказу его не меняет.
Второй платёж по уже оплаченному заказу только добавляет примечание: проверьте в бэк-офисе ifthenpay, не является ли это дублем. Возвращённые заказы и заказы, отменённые после оплаты, никогда не открываются снова.
Блок оплаты ifthenpay
На странице заказа показывается блок ifthenpay payment с попытками оплаты заказа (дата, способ, значок Sandbox для тестовых платежей, сумма, организация (entity) и референс Multibanco или замаскированный телефон MB WAY, ID запроса ifthenpay и статус), предупреждение Manual review, пока заказ находится в статусе ifthenpay payment on hold, и ifthenpay notes заказа.
Возвраты
Возвраты из PrestaShop не поддерживаются. Оформите возврат платежа в бэк-офисе ifthenpay и вручную зафиксируйте его в PrestaShop. Callback о возврате (DEVOLVIDO) только добавляет примечание. Другие статусы, которые сообщает ifthenpay, также только добавляют примечание.
Лицензионный ключ
Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox ifthenpay Gateway — первый блок на странице Modules > Module Manager > VibeFox ifthenpay Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-ifthenpay и ссылка Manage licenses and domains in your account, которая открывает вашу учётную запись vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку бэк-офиса (включены английский и русский).
Если ключ не принят, блок указывает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в вашей учётной записи нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.
Один ключ работает на одном домене: домене основного магазина, в том числе при мультимагазинной настройке. Удаление ключа из магазина не освобождает его слот домена. Освободите слот в своей учётной записи vibefox.net.
Без активного ключа ifthenpay не показывается покупателям при оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Магазин PrestaShop не знает, что вы вошли в бэк-офис, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но нельзя протестировать при оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются.
Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется, пока вы работаете в бэк-офисе: раз в день в течение первых 14 дней после ввода ключа, затем раз в неделю. Cron-задание не нужно. При удалении или сбросе модуля лицензионный ключ и статус лицензии всегда удаляются.
Устранение неполадок
ifthenpay не появляется при оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включено, что заполнен ключ выбранного Payment Method, что валюта корзины EUR и что сумма находится в пределах от 0,01 до 99 999,99 EUR. В Payment > Preferences проверьте, что модуль разрешён для EUR, страны покупателя и группы покупателя.
Покупатель оплатил, но заказ остаётся в статусе Awaiting ifthenpay payment или заказ не создан: callback не доходит до вашего магазина. Проверьте, что ifthenpay активировал callback URL и антифишинговый ключ для используемого вами ключа и что URL соответствует выбранному способу. Магазин должен быть доступен из интернета, а не на localhost и не за логином. Ищите строки Callback rejected в поле Log на странице модуля.
Callback отвечает 403 Forbidden: антифишинговый ключ в callback отсутствует или отличается от ключа в настройках. Повторно отправьте ifthenpay ключ, показанный в настройках.
Callback отвечает 503 Not configured: антифишинговый ключ ещё не создан. Откройте настройки модуля один раз; ifthenpay повторит callback.
Callback отвечает 503 Busy: в этот момент та же корзина обрабатывалась другим запросом. ifthenpay повторит callback.
Callback отвечает Order not found: референс или запрос не относится к платежу этого модуля, либо корзина была оформлена с другим способом оплаты.
Почему оплаченный заказ перевели на удержание? Полученная сумма отличалась от суммы заказа, либо платёж пришёл после отмены заказа. Прочитайте примечания в блоке ifthenpay payment, проверьте платёж в бэк-офисе ifthenpay и вручную завершите или возвратите заказ.
Не удалось отправить запрос MB WAY: номер телефона не привязан к MB WAY или введён в неверном формате. Используйте 912 345 678 или 351#912345678 для номеров других стран.
Тестовый режим и MB WAY: у ifthenpay нет песочницы MB WAY; используйте тестовый ключ, предоставленный ifthenpay.
Удаление
Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox ifthenpay Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete Data on Uninstall включено, настройки модуля, антифишинговый ключ и журнал удаляются; после повторной установки создаётся новый антифишинговый ключ, который нужно снова отправить ifthenpay. Если опция выключена, все настройки сохраняются для будущей повторной установки. Записи платежей ifthenpay (референсы и ID запросов) и статусы заказа Awaiting ifthenpay payment и ifthenpay payment on hold всегда сохраняются, чтобы callback по ранее выпущенным референсам находили свои заказы после повторной установки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.
ifthenpay — товарный знак его правообладателя. Этот модуль не связан с ifthenpay и не одобрен ifthenpay.