VibeFox Omise for WooCommerce — Допомога

Вимоги

WordPress: 6.2 або новіша версія.

WooCommerce: 8.0 або новіша, встановлений і активний. Плагін не активується без нього; якщо WooCommerce вимкнути пізніше, шлюз не завантажується і показується сповіщення для адміністратора.

PHP: 8.0 або новіша версія.

HTTPS: поля картки розміщені на вашій сторінці оформлення замовлення, тому вона має працювати через HTTPS і не містити ненадійних скриптів. Дані картки все одно ніколи не потрапляють на ваш сервер. Omise надсилає вебхуки лише на адреси HTTPS.

Валюта магазину: одна з THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. Для інших валют спосіб оплати на сторінці оформлення замовлення приховується.

Обліковий запис Omise: потрібні відкритий і секретний ключі вашого облікового запису Omise для тестового та робочого режимів, які можна знайти в розділі Settings > Keys панелі Omise, а також кінцева точка вебхука в розділі Settings > Webhooks (див. Налаштування).

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

Встановлення

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна і натисніть Install Now. Також можна завантажити папку wcp_omise_payment до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Omise > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії у верхній частині сторінки і натисніть Activate.

5. Введіть тестові та робочі ключі Omise і додайте в панелі Omise URL вебхука, який показано на сторінці налаштувань (див. Налаштування).

6. Увімкніть Enable/Disable. Перевірте оплату в тестовому режимі тестовою карткою Omise, наприклад 4242 4242 4242 4242, а потім зніміть позначку з Test mode.

Налаштування

Усі параметри розміщені на одній сторінці: WooCommerce > Settings > Payments > Omise. Над полями сторінка показує Test mode is on — orders are charged with the test keys, no real money is moved., поки тестовий режим увімкнено, і попереджає, якщо немає відкритого або секретного ключа поточного режиму чи якщо Omise не підтримує валюту магазину. В обох випадках спосіб оплати приховується на сторінці оформлення замовлення. У списку способів оплати Omise позначено як такий, що потребує налаштування, доки не введено обидва ключі поточного режиму.

Загальні

Enable/Disable: Enable card payments via Omise вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

Title: назва способу оплати, яку бачать покупці на сторінці оформлення замовлення. За замовчуванням: Credit / Debit Card.

Description: текст над формою картки на сторінці оформлення замовлення. За замовчуванням: Pay securely with your credit or debit card via Omise.

Ключі API

Ключі знаходяться в панелі Omise, у розділі Settings > Keys. Тестові ключі починаються з pkey_test_ і skey_test_, робочі — з pkey_ і skey_. Під час збереження ключ з неправильним префіксом (наприклад, тестовий ключ у робочому полі) відхиляється з помилкою, і зберігається попереднє значення.

Test mode: Use the test keys (no real charges). Перемикає обидва ключі. Повернення, списання та перевірки статусу замовлення завжди використовують ключі того режиму, у якому оплачено замовлення. За замовчуванням: увімкнено.

Test public key: відкритий ключ тестового режиму, pkey_test_...

Test secret key: секретний ключ тестового режиму, skey_test_...

Live public key: відкритий ключ робочого режиму, pkey_...

Live secret key: секретний ключ робочого режиму, skey_...

Оплата та вебхук

У цьому розділі показано URL вебхука вашого магазину. Він має такий вигляд: https://your-site/wp-json/omise-payment/v1/webhook. Скопіюйте його точно так, як його показано в налаштуваннях, і додайте в панелі Omise в розділі Settings > Webhooks (лише HTTPS). Плагін обробляє такі події:

Вмісту вебхука ніколи не довіряють: платіж має збігатися з тим, що збережено в замовленні, а його статус повторно запитується через API Omise з ключами того режиму, у якому оплачено замовлення. Без вебхука замовлення, для якого покупець закрив браузер під час 3-D Secure, залишається «На утриманні», доки ви не запустите Omise: Sync payment status, а списання, зроблені в панелі Omise, автоматично не підхоплюються.

Payment action: що відбувається із сумою на картці.

Per-charge webhook: Send the webhook URL with every charge. Корисно, коли кілька магазинів використовують один обліковий запис Omise. Працює лише якщо сайт використовує HTTPS; інакше використовується вебхук із панелі. За замовчуванням: вимкнено.

Додатково

Debug log: Log API requests and payment events записує кроки оплати в WooCommerce > Status > Logs, джерело wcp_omise_payment. Ключі, токени та дані картки ніколи не записуються в журнал. За замовчуванням: вимкнено.

Delete data on uninstall: Remove the settings and debug logs when the plugin is deleted. За замовчуванням: вимкнено.

Оформлення замовлення

Покупець обирає спосіб оплати (за замовчуванням Credit / Debit Card) і заповнює форму картки: Name on card, Card number, Expiry month (MM), Expiry year (YYYY) і Security code (CVV). У тестовому режимі форма показує TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made.. Після оформлення замовлення Omise.js перетворює картку на одноразовий токен у браузері. Поля картки ніколи не надсилаються на ваш сервер.

Ваш магазин створює списання секретним ключем на суму замовлення у валюті замовлення. Описом списання є назва магазину та номер замовлення, а ID замовлення зберігається в метаданих списання. Якщо банк вимагає 3-D Secure, покупця перенаправляють у банк і назад до вашого магазину. Результат завжди повторно запитується через API Omise.

Замовлення позначається оплаченим лише після підтвердження Omise: списання має бути захоплене, а сума та валюта мають відповідати замовленню. За Authorize only замовлення переходить у статус «На утриманні» після успішної авторизації. Покупець бачить сторінку підтвердження замовлення.

Якщо картку відхилено, покупець залишається на сторінці оформлення з повідомленням Payment failed: і причиною, наприклад недостатньо коштів, невірний код безпеки або відмова банку-емітента, і може повторити спробу. Після невдалого 3-D Secure покупця переводять на сторінку Pay for order. Якщо оплату не вдається підтвердити одразу після 3-D Secure, покупець бачить We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again.

Повторна спроба ніколи не списує кошти двічі: якщо попереднє списання замовлення вже оплачене або авторизоване, замовлення завершується без нового списання. Незавершена спроба 3-D Secure спливає до створення нового списання.

Спосіб оплати працює в класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний із WooCommerce High-Performance Order Storage (HPOS).

Плагін приймає лише картки. В ньому немає інших способів оплати Omise (PromptPay, TrueMoney, мобільний банкінг, розстрочка, Konbini, PayNow), збережених карток чи клієнтів Omise, підписок і часткового списання.

Замовлення та повернення

Статуси замовлення

Очікує оплати: покупець на сторінці 3-D Secure або ще не оплатив замовлення.

Обробляється: оплату підтверджено. Замовлення лише з віртуальними товарами для завантаження переходять у статус «Виконано», як звичайно в WooCommerce. Нотатка до замовлення показує суму, ID списання та спосіб підтвердження (оформлення замовлення, повернення з 3-D Secure, вебхук, ручне списання або ручна синхронізація). ID транзакції — це ID списання Omise (chrg_...).

На утриманні, очікує списання: картку авторизовано за допомогою Authorize only. Використайте Omise: Capture payment або Omise: Void authorization.

На утриманні, очікує підтвердження: Omise ще не підтвердила оплату, наприклад покупець закрив браузер під час 3-D Secure. Вебхук або Omise: Sync payment status оновлює замовлення.

На утриманні, розбіжність: сума або валюта списання відрізняються від замовлення. Нотатка показує обидва значення. Перевірте замовлення та завершіть його або поверніть оплату.

Невдало: оплату відхилено. Оплачене замовлення ніколи не понижується через подальшу подію про помилку.

Скасовано: строк дії списання минув або авторизацію анульовано.

Якщо для замовлення, яке вже Скасовано або Повернено, надходить оплачене чи авторизоване списання, замовлення не відкривається знову. Нотатка просить перевірити панель Omise та вручну повернути кошти або відкрити замовлення.

Дії із замовленням

Omise: Capture payment: списує повну авторизовану суму. Показується лише для авторизованих замовлень.

Omise: Void authorization: анулює авторизацію; гроші не списуються, замовлення скасовується. Показується лише для авторизованих замовлень.

Omise: Sync payment status: зчитує списання з Omise та оновлює замовлення. Нотатка також показує загальну суму, повернену в Omise.

Повернення коштів

Відкрийте замовлення, натисніть Refund, введіть суму і натисніть Refund via Omise. Підтримуються повне та часткове повернення. Повернення надсилається в тому режимі, у якому було здійснено оплату, тож секретний ключ цього режиму має бути заповнений. Успішне повернення додається до нотаток замовлення з ID повернення Omise. Для авторизації, яка ще не захоплена, можливе лише повне повернення, і воно анулює авторизацію. Якщо Omise відхиляє повернення, WooCommerce показує Refund failed. з повідомленням Omise, і повернення не реєструється.

Повернення, зроблені в панелі Omise, не імпортуються як повернення WooCommerce. Omise: Sync payment status показує загальну суму повернень; за потреби створіть відповідні ручні повернення в WooCommerce.

Ліцензійний ключ

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розміщено у верхній частині WooCommerce > Settings > Payments > Omise. Вставте ключ у поле License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, і ваш домен. Використовуйте Check now, щоб знову перевірити статус, Change key, щоб ввести інший ключ, і Remove key, щоб видалити його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

Один ключ працює на одному домені. Видалення ключа з сайту не звільняє місце для домену. Звільніть його у своєму обліковому записі vibefox.net.

Без активного ключа Omise не відображається покупцям на сторінці оформлення замовлення. Якщо оплату все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Адміністратори магазину, які ввійшли в систему, як і раніше бачать спосіб оплати, позначений як (unlicensed — visible to admins only), щоб ви могли налаштувати та перевірити плагін до придбання ключа. Нагадування з'являється на сторінці Plugins та на сторінках WooCommerce. Наявні замовлення не змінюються: оплати, які вже розпочато, як і раніше підтверджуються, а списання та повернення працюють.

Коли ліцензія завершується, плагін продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється у фоновому режимі.

Усунення несправностей

Omise не з'являється на сторінці оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, введено обидва ключі поточного режиму (тестові в тестовому режимі, інакше робочі) і валюта підтримується. На сторінці Pay for order враховується валюта замовлення. Сторінка налаштувань показує попередження, якщо ключі або валюта неправильні.

Оплату пройдено, але замовлення залишається в статусі Очікує оплати або На утриманні: вебхук не працює. У панелі Omise перевірте, що URL вебхука точно такий, як у налаштуваннях, і використовує HTTPS. Потім виконайте Omise: Sync payment status для замовлення. Увімкніть Debug log, щоб побачити відповіді вебхука.

Вебхук відповідає Earlier charge of the order, order not changed: подія стосується попередньої спроби замовлення, яку замінила повторна спроба. Замовлення не змінюється. Якщо це попереднє списання в Omise все ще оплачене або авторизоване, одна нотатка до замовлення повідомить про це: перевірте в панелі Omise можливу подвійну оплату та поверніть або анулюйте її там.

Вебхук відповідає Charge ID does not match order: списання в події належить іншому замовленню. Нічого не змінюється.

Вебхук відповідає Order is being processed, retry later або Failed to verify charge: замовлення було заблоковано іншим запитом або API Omise було недоступне. Omise повторить вебхук.

Помилка під час збереження: key must start with ... або must be a live key: ключ вставлено в неправильне поле. Тестові ключі починаються з pkey_test_ / skey_test_, робочі — з pkey_ / skey_.

Покупець бачить Card payments are temporarily unavailable: ключі неправильні або токен картки належить іншому режиму (тестовий токен у робочому режимі або навпаки). Перевірте ключі та Test mode.

Покупець бачить We could not reach the payment provider: під час створення списання від Omise не надійшла коректна відповідь. Списання могло бути створено; нотатка до замовлення просить перевірити панель Omise, перш ніж знову стягувати кошти за замовлення.

Покупець бачить This order is already being paid: оформлення замовлення надіслано двічі одночасно. Покупець має почекати та перевірити електронну пошту, перш ніж повторити спробу.

Замовлення «На утриманні» після оплати: прочитайте нотатку до замовлення. Замовлення очікує на списання, Omise ще не підтвердила оплату, або сума чи валюта відрізняються від замовлення.

Повернення не виконується з повідомленням про режим: оплату було здійснено в тестовому або робочому режимі, а секретний ключ цього режиму не заповнено. Введіть його та повторіть спробу.

Часткове повернення для авторизованого замовлення не виконується: оплата лише авторизована. Спочатку списіть її або поверніть повну суму, щоб анулювати авторизацію.

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть місце у своєму обліковому записі vibefox.net і натисніть Check now. Якщо адресу сайту змінено, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати за останнім відомим статусом.

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть плагін на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування шлюзу та журнали видаляються, лише якщо було увімкнено Delete data on uninstall. Інакше вони зберігаються для повторного встановлення. Дані Omise, збережені в замовленнях, належать до історії платежів і завжди зберігаються. Наявні замовлення зберігають свої нотатки про оплату та ID транзакцій.

Omise є торговельною маркою її власника. Цей плагін не пов'язаний з Omise і не схвалений компанією Omise.