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 і не схвалений нею.