VibeFox ECPay for WooCommerce — Помощь
Требования
WordPress: 6.0 или новее.
WooCommerce: 8.0 или новее, установлен и активен.
PHP: 8.0 или новее.
Валюта магазина: новый тайваньский доллар (TWD). ECPay принимает платежи только в TWD, и способ оплаты скрывается, если магазин или оплачиваемый заказ использует другую валюту. Суммы отправляются в целых TWD, так как ECPay не принимает десятичные значения: итоговые суммы заказа округляются до целого доллара. Используйте 0 знаков после запятой для цен в TWD, чтобы избежать округления.
Учётная запись ECPay: для реальных платежей нужны MerchantID, HashKey и HashIV вашей учётной записи мерчанта ECPay из бэк-офиса мерчанта ECPay (vendor.ecpay.com.tw). Для тестирования учётная запись ECPay не нужна.
Доступ к сайту: ваш сайт должен быть доступен из интернета по HTTP/HTTPS на порту 80/443, чтобы ECPay мог доставлять уведомления об оплате. Режим обслуживания, межсетевой экран или базовая аутентификация перед сайтом блокируют их.
Лицензионный ключ VibeFox: приобретается на vibefox.net. Один ключ работает на одном домене.
Установка
1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку wcp_ecpay_payment_gateway в /wp-content/plugins/ по FTP.
2. Нажмите Activate. WooCommerce должен быть активен.
3. Откройте настройки: WooCommerce > Settings > Payments > ECPay (綠界) > Manage, либо нажмите Settings под названием плагина на странице плагинов.
4. Введите лицензионный ключ VibeFox в блоке лицензии в верхней части страницы и нажмите Activate.
5. Включите Enable/Disable, выберите способы оплаты и оставьте Test Mode включённым для первых тестов. В песочнице можно оплатить тестовой картой ECPay 4311-9522-2222-2222 (любая будущая дата окончания срока действия, CVV 222, код 3-D Secure со страницы песочницы).
6. Для реальных платежей введите MerchantID, HashKey и HashIV (см. раздел Настройка) и снимите флажок Test Mode.
Настройка
Все настройки находятся на одной странице: WooCommerce > Settings > Payments > ECPay (綠界). Над полями страница показывает ошибку, если валюта магазина не TWD (в этом случае ECPay не отображается при оформлении заказа), и если в рабочем режиме не заданы MerchantID, HashKey и HashIV. Пока включён тестовый режим, страница предупреждает, что платежи отправляются в песочницу ECPay с публичным тестовым мерчантом 3002607, что деньги не списываются, и что любой, кто знает публичные ключи песочницы, может подтверждать тестовые заказы, поэтому тестовый режим нужно отключить перед приёмом реальных заказов.
Общие
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: Enable sandbox/test mode отправляет платежи в песочницу ECPay (payment-stage.ecpay.com.tw) с публичным тестовым мерчантом ECPay 3002607. Реальные деньги не списываются. Указанные ниже учётные данные используются только при отключённом тестовом режиме. По умолчанию: включено.
Merchant ID: ваш Merchant ID ECPay (рабочая среда). Игнорируется в тестовом режиме.
Hash Key: ваш Hash Key ECPay (рабочая среда). Игнорируется в тестовом режиме.
Hash IV: ваш Hash IV ECPay (рабочая среда). Игнорируется в тестовом режиме.
Пробелы и разрывы строк во вставленных учётных данных ломают все подписи, поэтому они удаляются при сохранении, и страница сообщает об этом.
Параметры оплаты
Enabled Payment Methods: способы оплаты, предлагаемые покупателям. При выборе нескольких покупатель выбирает способ при оформлении заказа. Заказы ATM, CVS и Barcode остаются в статусе «На удержании» до оплаты покупателем. Нужно выбрать хотя бы один способ; если не выбран ни один, включается Credit Card. По умолчанию: Credit Card.
Default Payment Method: предварительно выбранный способ. Он должен быть одним из включённых способов; иначе используется первый включённый способ. По умолчанию: Credit Card.
Order Prefix: префикс номера транзакции ECPay (MerchantTradeNo), до 5 букв или цифр. Остальные символы удаляются при сохранении. Полезно, если несколько магазинов используют одну учётную запись ECPay: дайте каждому магазину свой префикс. По умолчанию: EC.
Уведомления об оплате
ECPay отправляет результаты оплаты в ваш магазин. В этом разделе показан URL уведомлений. Он выглядит так: https://your-site/wc-api/ecpay_p_callback/. URL отправляется с каждым платежом, поэтому в ECPay ничего настраивать не нужно, но он должен быть доступен из интернета по порту 80/443, без режима обслуживания, межсетевого экрана или базовой аутентификации перед ним.
Каждое уведомление проверяется по подписи CheckMacValue с ключами той среды (тестовой или рабочей), в которой был начат платёж. Уведомления без действительной подписи отклоняются, и ECPay отправляет их повторно. Без уведомления ни один заказ не отмечается оплаченным; проверьте платёж в бэк-офисе ECPay.
Дополнительно
Enable Logging: Log payment events and API calls записывает ID заказов, номера транзакций, суммы и коды возврата ECPay в WooCommerce > Status > Logs, источник wcp_ecpay_payment_gateway. Ключи и данные покупателя не записываются. По умолчанию: выключено.
Delete Data on Uninstall: Delete all plugin data when uninstalling. Удаляет все настройки, журналы и метаданные заказов этого плагина. По умолчанию: выключено.
Оформление заказа
Покупатель выбирает способ оплаты (по умолчанию ECPay (綠界)). При включении нескольких способов покупатель также выбирает Credit Card, ATM (Virtual Account), CVS (Convenience Store) или Barcode. Пока включён тестовый режим, способ оплаты показывает TEST MODE — ECPay sandbox, no real money is charged.
После оформления заказа покупатель видит Redirecting to ECPay for payment. Please wait... и перенаправляется на страницу оплаты ECPay, с кнопкой Proceed to ECPay на случай, если перенаправление не началось. Итоговая сумма заказа отправляется в целых TWD с названиями и количеством товаров. Страница ECPay открывается на традиционном китайском для тайваньского и гонконгского языков сайта, на упрощённом китайском, корейском или японском для этих языков и на английском для всех остальных.
Заказ отмечается оплаченным только после того, как ECPay подтвердит это подписанным уведомлением сервера. Если покупатель возвращается на страницу получения заказа до прихода подтверждения, страница показывает We have not received a payment confirmation from ECPay for this order yet. If you did not complete the payment, you can try again: с кнопкой Pay.
Для ATM, CVS и Barcode покупатель сначала получает платёжные реквизиты. Заказ переводится в статус «На удержании», а код банка и виртуальный счёт, код оплаты в магазине у дома или штрихкоды, сумма и дата Pay before показываются в разделе ECPay payment instructions на странице благодарности, в My account > Orders и в письме о заказе на удержании. Когда покупатель оплачивает, ECPay отправляет ещё одно уведомление, и заказ отмечается оплаченным.
Каждое посещение страницы оплаты создаёт новый номер транзакции ECPay, потому что ECPay отклоняет повторно использованные номера. Поэтому страница Pay for order и повторные попытки после неудачного платежа работают, а уведомления по любому из этих номеров привязываются к заказу. У заказа может быть до 30 попыток оплаты.
Собственные лимиты сумм ECPay по способам оплаты, например для платежей в магазинах у дома, проверяются на странице ECPay, а не при оформлении заказа.
Способ оплаты работает на классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Он совместим с WooCommerce High-Performance Order Storage (HPOS).
Плагин принимает только разовые платежи на странице ECPay. В нём нет возвратов из WooCommerce, сохранённых карт, подписок или периодических платежей (定期定額), рассрочки, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, электронных счетов-фактур или логистики, а также нет серверного запроса статуса: если ваш сайт не может получить уведомление, проверьте платёж в бэк-офисе ECPay.
Заказы
Статусы заказа
Pending payment: покупатель был перенаправлен на ECPay и ещё не оплатил, либо уведомление ещё не пришло.
On hold, waiting for payment: покупатель выбрал ATM, CVS или Barcode и получил платёжные реквизиты. В заметке к заказу показаны код банка и виртуальный счёт, код оплаты или штрихкоды и срок.
Processing: оплата подтверждена (значение по умолчанию WooCommerce; заказы только с виртуальными загружаемыми товарами переходят в статус «Выполнен»). В заметке к заказу показаны TradeNo ECPay, тип платежа, сумма и номер транзакции. Идентификатор транзакции — это TradeNo ECPay.
On hold after payment: ECPay сообщил сумму или валюту, отличную от заказа, платёж из песочницы пришёл после перехода в рабочий режим (реальные деньги не списывались), либо платёж пришёл после отмены заказа. Заметка к заказу объясняет причину. Сравните с бэк-офисом ECPay и завершите или оформите возврат по заказу вручную.
Failed: ECPay сообщил, что последняя попытка оплаты не удалась. В заметке показаны код возврата и сообщение ECPay. Покупатель может попробовать снова.
Повторные уведомления игнорируются. Оплаченный, отменённый или возвращённый заказ никогда не открывается повторно по старому уведомлению. Повторный платёж по уже оплаченному заказу, например из двух вкладок браузера, записывается как заметка к заказу, чтобы вы могли оформить возврат в бэк-офисе ECPay. Имитированные платежи, запущенные из бэк-офиса ECPay, только записываются в заметки и никогда не отмечают заказ оплаченным, так как ECPay не списывает за них деньги.
Возвраты
Возвраты из WooCommerce недоступны. Оформите возврат платежа в бэк-офисе ECPay, затем запишите возврат вручную в WooCommerce.
Лицензионный ключ
Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится в верхней части WooCommerce > Settings > Payments > ECPay (綠界). Вставьте ключ в поле License key и нажмите Activate. Блок показывает статус, например дату, до которой лицензия активна, и ваш домен. Используйте Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа с этого сайта. Ссылка Manage licenses and domains in your account открывает вашу учётную запись vibefox.net.
Один ключ работает на одном домене. Удаление ключа с сайта не освобождает занятый им слот домена. Освободите слот в вашей учётной записи vibefox.net.
Без активного ключа ECPay не показывается покупателям при оформлении заказа. Если платёж всё же запущен, покупатель видит This payment method is not available. Please choose another one. Вошедшие в систему управляющие магазином всё равно видят способ оплаты с отметкой (unlicensed — visible to admins only), поэтому вы можете настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице плагинов и на страницах WooCommerce. На существующие заказы это не влияет: уже начатые платежи всё равно подтверждаются.
Когда лицензия истекает, плагин продолжает работать, но обновления и поддержка требуют продления. Статус автоматически проверяется повторно в фоновом режиме.
Устранение неполадок
ECPay не отображается при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён, валюта магазина TWD, и что в рабочем режиме заданы Merchant ID, Hash Key и Hash IV. Страница настроек показывает ошибку в каждом из этих случаев.
Платёж прошёл, но заказ остаётся в статусе «Ожидает оплаты»: уведомление 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.
Покупатель видит The order total is too small for ECPay.: итоговая сумма заказа после округления меньше 1 TWD, и её нельзя оплатить через ECPay.
Заказ в статусе «На удержании» с заметкой о несовпадении суммы: сумма, указанная ECPay, отличается от итоговой суммы заказа, например заказ был изменён после того, как покупатель начал оплату. Сравните с бэк-офисом ECPay и завершите или оформите возврат по заказу вручную.
Заказ в статусе «На удержании» после платежа из песочницы: платёж был выполнен в тестовом режиме, но магазин теперь в рабочем режиме. Реальные деньги не списывались. Проверьте заказ вручную.
Покупатель видит Too many payment attempts for this order: заказ достиг 30 попыток оплаты. Попросите покупателя оформить новый заказ.
Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите слот в вашей учётной записи vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.
Удаление
Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте и удалите его на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки, данные ECPay, сохранённые в заказах, и журналы удаляются только если была включена опция Delete Data on Uninstall. Иначе они остаются для последующей переустановки. Существующие заказы сохраняют свои заметки об оплате и идентификаторы транзакций.
ECPay является товарным знаком своего правообладателя. Этот плагин не связан с ECPay и не одобрен ECPay.