VibeFox eWAY for PrestaShop — Помощь

Требования

PrestaShop: от 8.0 до 9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

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

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

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

Установка

1. В панели администратора перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По завершении загрузки нажмите Configure или позже найдите VibeFox eWAY Payment Gateway в списке модулей и нажмите Configure.

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

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

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

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

При установке модуль создаёт статус заказа eWAY payment on hold. PrestaShop предлагает новый платёжный модуль для всех валют, стран и групп клиентов. Ограничить их можно в разделе Payment > Preferences.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox eWAY Payment Gateway > Configure. У каждого раздела есть своя кнопка 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.

eWAY

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

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

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely using your credit card via eWAY. You will be redirected to the eWAY secure payment page.

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

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

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

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

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

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

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

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

Clear saved credentials: отметьте ключ или пароль и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

Return URL / re-checks: в eWAY не нужно настраивать ни webhook, ни URL возврата, поскольку URL возврата передаётся с каждым платежом. Это поле показывает необязательный URL cron. Вызывайте его из cron-задачи сервера, например каждые 15 минут. Если покупатель оплатил и закрыл браузер, не вернувшись в магазин, платёж запрашивается у eWAY примерно через час, и заказ создаётся. Если eWAY недоступен, проверка повторяется до трёх раз. Держите этот URL в секрете: в нём есть токен, а вызов с неверным токеном получает ответ Forbidden.

Заказы

Order Status on Success: статус заказа после подтверждения платежа eWAY.

Подтверждённые сумма или валюта, не совпадающие с заказом, всегда переводят заказ в eWAY payment on hold.

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

Debug log: записывает вызовы API и результаты платежей в logs/eway_p_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Данные карт, ключи, пароли, e-mail покупателей и коды доступа не записываются. Ошибки записываются всегда. По умолчанию: выключено.

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

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

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

На шаге оплаты покупатель выбирает способ оплаты (по умолчанию Credit Card (eWAY)) и подтверждает. Модуль запрашивает у eWAY страницу оплаты на сумму корзины в валюте корзины, с PS- и номером корзины в качестве справочного номера счёта, а также с платёжным адресом и e-mail покупателя, и перенаправляет покупателя на eWAY Responsive Shared Page. Там покупатель платит картой. Списание происходит сразу. На этом этапе заказа ещё нет.

После оплаты покупатель возвращается в ваш магазин. Модуль не доверяет браузеру: он запрашивает у eWAY по каналу сервер-сервер результат страницы оплаты, созданной для этой корзины. Заказ отмечается оплаченным только после подтверждения eWAY и если подтверждённые сумма и валюта совпадают с корзиной. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с Your payment with eWAY has been received. Для заказа на удержании страница показывает 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. Корзина во всех случаях сохраняется.

Покупатель может повторить попытку. Перед созданием новой страницы оплаты предыдущая страница корзины проверяется у eWAY. Если она уже оплачена, создаётся заказ вместо повторного списания. Если eWAY не может создать страницу оплаты, покупатель остаётся на оформлении заказа с коротким сообщением, например Payment error: Unable to connect to eWAY. Please try again. или eWAY could not start the payment с кодами ошибок eWAY.

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

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

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

No order yet: покупатель был перенаправлен на eWAY и не оплатил, отменил, платёж был отклонён или результат пока не удалось получить. Существует только корзина.

Payment accepted or Delivered: платёж подтверждён. Статус следует за Order Status on Success. Платёж записывается с ID транзакции eWAY, а примечание показывает ID транзакции, код авторизации, ответ и режим (sandbox или рабочий).

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

Refunded: платёж полностью возвращён через модуль.

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

Блок оплаты eWAY

На странице заказа есть блок eWAY payment с ID транзакции, кодом авторизации, ответом eWAY, статусом, режимом и справочным номером счёта, суммой оплаты и возврата, бейджем Sandbox для тестовых платежей, историей возвратов и eWAY notes заказа.

Возвраты

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

Модуль не создаёт кредит-ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через eWAY. Возвраты, оформленные в MyeWAY, не синхронизируются с PrestaShop. При необходимости обновите заказ вручную.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox eWAY Payment Gateway — это первый блок на странице Modules > Module Manager > VibeFox eWAY Payment Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже показаны строка Product: presta-payment-eway и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Менять ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку back office (английский и русский включены).

Если ключ не принят, блок сообщает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

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

Без активного ключа eWAY не показывается покупателям при оформлении заказа. Если платёж всё же начат, покупатель видит Этот способ оплаты недоступен. Выберите другой. Витрина PrestaShop не знает, что вы вошли в back office, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но нельзя проверить при оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты работают.

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

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

eWAY does not appear at checkout: проверьте, что лицензия активна, Enable/Disable включён, ключ и пароль API текущего режима заполнены (поля sandbox в режиме sandbox, рабочие поля в рабочем режиме) и валюта корзины — AUD, NZD, SGD, HKD или MYR. На странице настроек появляется предупреждение, если учётные данные не заполнены. В Payment > Preferences проверьте, разрешён ли модуль для валюты корзины, страны покупателя и группы покупателя.

The payment went through, but no order was created: покупатель не вернулся из eWAY, или запросить eWAY в этот момент не удалось. eWAY не отправляет уведомлений для Shared Page. Настройте URL cron из Return URL / re-checks: он подхватит платёж примерно через час. Проверьте транзакцию в MyeWAY и посмотрите поле Log на странице модуля.

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

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

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

The customer sees We could not check the status of your previous payment attempt: другой запрос обрабатывал ту же корзину. Покупатель может повторить попытку через минуту.

Order is eWAY payment on hold after payment: прочитайте eWAY notes в блоке eWAY payment (см. раздел «Статусы заказа»), затем обработайте заказ или оформите возврат платежа.

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

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

Для разработчиков: в README модуля описан хук actionWcpEwaySupportedCurrencies, на случай если ваша учётная запись eWAY подключена к дополнительным валютам.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox eWAY Payment Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete all plugin data on uninstall включено, настройки шлюза и журнал удаляются. Если выключено, все настройки сохраняются для повторной установки. Платёжные данные eWAY по заказам и статус заказа eWAY payment on hold всегда сохраняются, поэтому заказы, оплаченные ранее, можно вернуть и после повторной установки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

eWAY — товарный знак его правообладателя. Этот модуль не связан с eWAY и не одобрен eWAY.