VibeFox ECPay for PrestaShop — Помощь

Требования

PrestaShop: 8.0 до 9.x.

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

Валюта: новый тайваньский доллар (TWD). ECPay принимает платежи только в TWD, поэтому способ оплаты показывается только тогда, когда корзина покупателя в TWD. Добавьте TWD в разделе International > Localization > Currencies, если её нет в вашем магазине. Суммы передаются в целых TWD, так как ECPay не принимает дробные значения: итоги корзины округляются до ближайшего доллара. Для цен в TWD используйте 0 знаков после запятой, чтобы избежать округления.

Учётная запись ECPay: для реальных платежей нужны MerchantID, HashKey и HashIV вашей учётной записи мерчанта ECPay из бэк-офиса мерчанта ECPay (vendor.ecpay.com.tw). Для тестирования учётная запись ECPay не нужна.

Доступ к сайту: ваш магазин должен быть доступен из интернета по HTTP/HTTPS на порту 80/443, чтобы ECPay мог передавать уведомления о платежах. Межсетевой экран или базовая аутентификация перед сайтом их блокируют.

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

Установка

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

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

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

4. Включите Enable/Disable, выберите способы оплаты и оставьте Test Mode включённым для первых тестов. Нажмите Save.

5. Для реальных платежей введите Merchant ID, Hash Key и Hash IV (см. раздел Конфигурация), выключите Test Mode и нажмите Save.

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

Конфигурация

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает ошибку, если в вашем магазине нет валюты TWD (тогда ECPay не отображается при оформлении заказа), или предупреждение, если валюта по умолчанию не TWD (тогда ECPay показывается только покупателям, которые платят в TWD). Она показывает ошибку, если в боевом режиме не заполнены MerchantID, HashKey и HashIV. Пока включён тестовый режим, она предупреждает, что платежи уходят в песочницу ECPay с публичным тестовым мерчантом 3002607, что деньги не списываются и что любой, кто знает публичные ключи песочницы, может подтвердить тестовые заказы, поэтому тестовый режим должен быть выключен до приёма реальных заказов.

ECPay (綠界)

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

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

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).

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

Найдите MerchantID, HashKey и HashIV в бэк-офисе мерчанта ECPay (vendor.ecpay.com.tw) в разделе System development management > System integration settings (系統開發管理 > 系統介接設定).

Test Mode: отправляет платежи в песочницу ECPay (payment-stage.ecpay.com.tw) с публичным тестовым мерчантом ECPay 3002607. Реальные деньги не списываются. Учётные данные ниже используются только при выключенном тестовом режиме. По умолчанию: включено. Пока режим включён, покупатели видят под способом оплаты надпись TEST MODE — ECPay sandbox, no real money is charged.

Merchant ID: ваш Merchant ID ECPay (боевой). В тестовом режиме игнорируется.

Hash Key: ваш Hash Key ECPay (боевой). В тестовом режиме игнорируется.

Hash IV: ваш Hash IV ECPay (боевой). В тестовом режиме игнорируется.

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

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

Способы оплаты

Enabled Payment Methods: способы оплаты, которые предлагаются покупателям. Если их больше одного, покупатель выбирает при оформлении заказа. Заказы ATM, CVS и штрихкодом остаются в статусе Awaiting ECPay payment, пока покупатель не оплатит. Должен быть выбран хотя бы один способ; если не выбран ни один, включается Credit Card, и страница сообщает об этом. По умолчанию: Credit Card.

Default Payment Method: способ, выбранный по умолчанию. Он должен быть одним из включённых способов; иначе используется первый включённый способ. По умолчанию: Credit Card.

Order Prefix: префикс номера транзакции ECPay (MerchantTradeNo), до 5 букв или цифр. Другие символы удаляются при сохранении, с сообщением. Полезно, когда несколько магазинов используют один аккаунт ECPay: задайте каждому магазину свой префикс. По умолчанию: EC.

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

ECPay передаёт результаты платежей в ваш магазин. Этот раздел показывает Notification URL. При понятных URL он выглядит так: https://your-shop/module/wcp_ecpay_payment_gateway/notify, возможно, с кодом языка, например /en/. URL передаётся с каждым платежом, поэтому в ECPay ничего настраивать не нужно, но он должен быть доступен из интернета по порту 80/443, без межсетевого экрана и базовой аутентификации перед ним. Режим обслуживания и ограничение по стране в вашем магазине его не блокируют.

Каждое уведомление проверяется по подписи CheckMacValue с ключами того окружения (тестового или боевого), в котором был начат платёж, и по MerchantID этого платежа. Уведомления без действительной подписи отклоняются, и ECPay отправляет их повторно. Без уведомления заказ не создаётся; проверьте платёж в бэк-офисе ECPay.

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

Enable Logging: записывает ID заказов, номера транзакций, суммы и коды ответов ECPay в logs/ecpay_p_debug.log.php в папке модуля. Этот файл нельзя открыть из браузера. Ключи и данные покупателей не записываются. Ошибки записываются всегда, даже когда этот переключатель выключен. По умолчанию: выключено.

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

Delete Data on Uninstall: если включено, при удалении модуля удаляются его настройки и журнал. Записи платежей ECPay и статусы заказов всегда сохраняются, поэтому существующие заказы продолжают работать после повторной установки. По умолчанию: выключено.

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

На шаге оплаты покупатель выбирает способ оплаты (по умолчанию ECPay (綠界)). Если включено несколько способов, покупатель также выбирает Credit Card, ATM (Virtual Account), CVS (Convenience Store) или Barcode в поле Payment Method.

После подтверждения покупатель видит Redirecting to ECPay for payment. Please wait... и перенаправляется на страницу оплаты ECPay; кнопка Proceed to ECPay доступна на случай, если перенаправление не началось. Сумма корзины передаётся в целых TWD вместе с названиями и количеством товаров. Страница ECPay открывается на традиционном китайском для тайваньского и гонконгского языков, на упрощённом китайском, корейском или японском для этих языков и на английском для всех остальных, в соответствии с языком магазина покупателя. На этом этапе заказа ещё не существует.

Заказ создаётся только после того, как ECPay подтвердит его подписанным уведомлением сервера. Когда покупатель нажимает ссылку возврата в магазин на странице ECPay и заказ уже существует, открывается стандартная страница подтверждения заказа. Она показывает Your ECPay payment has been received. для оплаченного заказа, Your ECPay payment was received and is being reviewed by the store. для заказа на удержании и инструкции по оплате для заказа ATM, CVS или штрихкодом, ожидающего оплаты. Если уведомление ещё не пришло, страница Payment confirmation показывает We have not received a payment confirmation from ECPay for this order yet. Your order will be created as soon as ECPay confirms the payment. с кнопками Check again и Back to checkout. Если ECPay сообщил о неудачном платеже, покупатель возвращается к оформлению заказа с сообщением The payment was not completed. You can try again or choose another payment method. Корзина сохраняется.

Для ATM, CVS и штрихкода покупатель сначала получает платёжные реквизиты. Заказ создаётся в статусе Awaiting ECPay payment, а код банка и виртуальный счёт, код оплаты в магазине у дома или штрихкоды, сумма и дата Pay before показываются в разделе ECPay payment instructions на странице подтверждения заказа и в деталях заказа в личном кабинете покупателя. Когда покупатель платит, ECPay присылает ещё одно уведомление, и заказ отмечается оплаченным. Инструкции по оплате не добавляются в письма PrestaShop.

Каждая попытка создаёт новый номер транзакции ECPay, потому что ECPay отклоняет повторно использованные номера. Поэтому повторные попытки после неудачного платежа работают, а если покупатель возвращается в браузере на страницу перенаправления, начинается новая попытка. У корзины может быть до 30 попыток оплаты. Как только у корзины появился заказ, оплатить её через оформление заказа нельзя; ожидающий заказ ATM или CVS оплачивается по уже выданным реквизитам.

Если оплату не удалось начать, покупатель остаётся на оформлении заказа с коротким сообщением, например The order total is too small for ECPay., когда итог после округления меньше 1 TWD. Лимиты сумм ECPay для каждого способа проверяются на странице ECPay, а не при оформлении заказа.

Модуль принимает разовые платежи только на странице ECPay. В нём нет возвратов из PrestaShop, сохранённых карт, подписок или периодических платежей (定期定額), рассрочки, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, электронных счетов-фактур или логистики, а также запроса статуса на стороне сервера: если ваш магазин не может получить уведомление, проверьте платёж в бэк-офисе ECPay.

Заказы

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

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

Awaiting ECPay payment: покупатель выбрал ATM, CVS или штрихкод и получил платёжные реквизиты. Заметка показывает код банка и виртуальный счёт, код оплаты или штрихкоды и срок оплаты.

Payment accepted: платёж подтверждён. Он записывается с TradeNo ECPay в качестве ID транзакции, а заметка показывает TradeNo, тип платежа, сумму и номер транзакции (с отметкой тестового режима для платежей песочницы).

ECPay payment on hold: ECPay сообщил сумму или валюту, отличающиеся от корзины (например, корзину изменили в другой вкладке после начала оплаты), платёж песочницы пришёл после перехода в боевой режим (реальные деньги не списывались), или платёж пришёл после отмены заказа (тогда платёж записывается). Заметка объясняет причину. Сверьтесь с бэк-офисом ECPay, затем обработайте заказ или верните платёж там.

Payment error: ECPay сообщил, что последний платёж ATM, CVS или штрихкодом по заказу, ожидающему оплаты, не прошёл. Заметка показывает код ответа ECPay и сообщение.

Повторные уведомления игнорируются. Оплаченный, возвращённый или отменённый заказ никогда не открывается заново из-за позднего отказа. Второй платёж по уже оплаченному заказу, например из двух вкладок браузера, записывается в заметку один раз, чтобы вы могли вернуть его в бэк-офисе ECPay. Имитированные платежи, запущенные из бэк-офиса ECPay, только отмечаются и никогда не помечают заказ оплаченным, потому что ECPay не списывает за них деньги.

Блок платежей ECPay

На странице заказа есть блок ECPay payment со всеми попытками оплаты заказа: MerchantTradeNo с отметкой Test mode для попыток песочницы, способ оплаты, сумма в TWD, статус, TradeNo ECPay, тип платежа и дата, а также код ответа ECPay. Ниже находятся ECPay notes заказа. Для заказа в статусе ECPay payment on hold блок напоминает сверить его с бэк-офисом ECPay.

Возвраты

Возвраты из PrestaShop недоступны. Верните платёж в бэк-офисе ECPay, затем вручную обновите заказ в PrestaShop. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через ECPay.

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

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

Без активного ключа ECPay не показывается покупателям при оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в back office, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать на оформлении заказа нельзя. Напоминание появляется в разделе Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются.

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

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

ECPay не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, корзина покупателя в TWD и, в боевом режиме, заполнены Merchant ID, Hash Key и Hash IV. В каждом из этих случаев страница настроек показывает сообщение. В разделе Payment > Preferences проверьте, что модуль разрешён для TWD, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: уведомление ECPay не дошло до вашего магазина (сайт недоступен, межсетевой экран, базовая аутентификация). ECPay повторяет отправку несколько раз. Транзакцию также можно проверить в бэк-офисе ECPay. Включите Enable Logging, чтобы увидеть уведомления, которые получил модуль; отклонённые уведомления в любом случае записываются как ошибки.

Уведомление отвечает 0|CheckMacValue verification failed: Hash Key или Hash IV не совпадают с вашей учётной записью ECPay либо платёж начат в другом окружении. Скопируйте их заново из бэк-офиса ECPay.

Уведомление отвечает 0|MerchantID mismatch: уведомление относится к другому мерчанту ECPay, чем тот, с которым начат платёж.

Уведомление отвечает 0|Order not found: номер транзакции не выпущен этим магазином, например когда несколько магазинов используют один аккаунт ECPay. Задайте каждому магазину свой Order Prefix.

Уведомление отвечает 0|Retry: корзина в этот момент обрабатывалась другим уведомлением, или заказ не удалось создать (например, модуль отключён). ECPay отправит уведомление повторно. Включите Enable Logging, чтобы увидеть причину.

URL уведомления показывает 0|Method not allowed in the browser: это нормально. URL принимает только запросы от ECPay.

Покупатель видит «The order total is too small for ECPay.»: итог корзины после округления меньше 1 TWD, и оплатить его через ECPay нельзя.

Покупатель видит «Too many payment attempts for this order»: в корзине 30 попыток оплаты. Попросите покупателя начать новую корзину.

Заказ в статусе ECPay payment on hold: прочитайте заметки в блоке ECPay payment (см. Статусы заказа), сверьте их с бэк-офисом ECPay, затем обработайте заказ или верните платёж там.

Разработчикам: хук actionEcpayPRequestParams позволяет другому модулю изменить параметры, отправляемые в ECPay; мерчант, номер транзакции и сумму им изменить нельзя.

Удаление

Откройте Modules > Module Manager, откройте меню рядом с VibeFox ECPay Payment Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete Data on Uninstall включено, настройки и журнал удаляются. Если выключено, все настройки сохраняются для последующей повторной установки. Записи платежей ECPay и статусы заказов Awaiting ECPay payment и ECPay payment on hold всегда сохраняются, поэтому поздние уведомления по старым платежам по-прежнему проверяются после повторной установки. Существующие заказы сохраняют свои платёжные заметки и ID транзакций.

ECPay — товарный знак его владельца. Модуль не аффилирован с ECPay и не одобрен ECPay.