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

Вимоги

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

WooCommerce: 7.0 або новіша, встановлено й активовано. Без нього плагін не активується.

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

HTTPS: сайту потрібен HTTPS, а KOMOJU має мати доступ до URL вебхука.

KOMOJU account: потрібні секретний ключ (sk_live_... і для тестового режиму sk_test_...) та секретний токен вебхука, створеного в панелі KOMOJU (див. «Налаштування»). Публічний ключ не потрібен.

Store currency: JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD або VND. Для інших валют спосіб приховано.

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

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

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

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

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

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

5. У панелі KOMOJU додайте вебхук з URL і подіями зі сторінки налаштувань та скопіюйте його секретний токен (див. «Налаштування»).

6. Введіть робочий секретний ключ і секретний токен робочого вебхука, а також тестові значення для sandbox. Увімкніть Enable/Disable та збережіть.

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

Усі налаштування на одній сторінці: WooCommerce > Settings > Payments > KOMOJU Payment. У тестовому режимі над полями відображається KOMOJU Sandbox Mode is enabled.. Сторінка попереджає про відсутність секретного ключа поточного режиму (спосіб приховується під час оформлення) або секретного токена вебхука (сповіщення KOMOJU відхиляються, тож konbini та перекази ніколи не підтверджуються), а також про непідтримувану валюту. У списку способів KOMOJU потребує налаштування, доки поточний режим не має секретного ключа; у sandbox показує тестову позначку.

Загальні

Enable/Disable: Enable KOMOJU Payment Gateway вмикає чи вимикає спосіб. Типово: off.

Title: назва способу для покупців під час оформлення. Типово: KOMOJU Payment.

Description: текст під способом під час оформлення. Типово: Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.

Робочі ключі API

Ключі в панелі KOMOJU: секретний ключ у Settings > API keys, секретний токен вебхука у Settings > Webhooks (спершу додайте туди показаний нижче URL вебхука).

Live Secret Key: ваш робочий секретний ключ KOMOJU. Починається з sk_live_.

Live Webhook Secret Token: секретний токен робочого вебхука. Перевіряє підпис кожного сповіщення.

Тестовий режим

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

Sandbox Mode: Enable test mode (use the test keys below, no real payments). Типово: off. Коли ввімкнено, над описом при оформленні показано Test mode.

Sandbox Secret Key: ваш тестовий секретний ключ KOMOJU. Починається з sk_test_.

Sandbox Webhook Secret Token: секретний токен тестового вебхука.

URL вебхука

Вебхук повідомляє магазин про платежі, зокрема відкладені konbini та перекази. У панелі KOMOJU у Settings > Webhooks додайте URL цього розділу для робочого й тестового режимів. Виглядає як https://your-site/wc-api/komoju_p_webhook/. Якщо URL сайту містять мовний префікс, скопіюйте адресу точно з налаштувань. Потім скопіюйте секретний токен кожного вебхука в Live Webhook Secret Token або Sandbox Webhook Secret Token.

Виберіть події:

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

Додатково

Invoice Prefix: префікс номерів замовлень для KOMOJU. Якщо кілька магазинів мають один обліковий запис KOMOJU, задайте кожному унікальний. Типово: WC-.

Enable Logging: Log KOMOJU events and API calls у WooCommerce > Status > Logs, джерело wcp_komoju_payment, без ключів і даних покупців. Помилки записуються завжди. Типово: off.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. Деактивація нічого не видаляє. Дані замовлень (ID платежів KOMOJU) завжди зберігаються. Типово: off.

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

Покупець вибирає спосіб (типово KOMOJU Payment) і оформлює замовлення. Плагін створює сесію KOMOJU на повну суму у валюті замовлення й направляє покупця на платіжну сторінку KOMOJU. Передаються платіжний e-mail, ім’я, платіжна адреса й адреса доставки, замовлені товари. Сторінка японською, англійською чи корейською залежно від мови сайту (англійською для інших). Там покупець вибирає спосіб. Доступність залежить від вашого облікового запису KOMOJU та валюти замовлення.

Після оплати покупець повертається до магазину. Плагін читає сесію через API KOMOJU з ключем режиму замовлення. Оплата позначається лише після підтвердження KOMOJU: підписаним вебхуком або читанням сесії після повернення. Якщо KOMOJU недоступний, покупець переходить на сторінку отриманого замовлення з We could not confirm the payment status with KOMOJU yet. If you completed the payment, your order will be updated automatically in a few minutes.

Для konbini й переказів покупець отримує квитанцію. Замовлення очікує оплати й завершується, коли покупець платить і KOMOJU надсилає вебхук. Якщо термін квитанції минув, замовлення скасовується.

Якщо платіж не завершено, покупець повертається на Pay for order з The payment was not completed. You can try again or choose another payment method. Нова спроба використовує відкриту сесію, якщо сума незмінна. Сесія зі старою сумою скасовується в KOMOJU, а оплачена тим часом підтверджує замовлення. Якщо неоплачене замовлення скасовано (вами, покупцем чи таймером утримання запасу WooCommerce), його відкрита сесія KOMOJU теж скасовується, і сплатити її вже неможливо.

Якщо KOMOJU не може почати платіж, покупець бачить коротке повідомлення, наприклад KOMOJU could not accept this payment: з причиною, KOMOJU payments are temporarily unavailable. Please choose another payment method or contact us. або Payment error: Could not connect to KOMOJU. Please try again in a moment. Подробиці додаються до приміток замовлення й журналу.

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

Немає форми картки на сайті, збережених карток і підписок. Плагін не обмежує способи: їх вибирають на сторінці KOMOJU. Ручного захоплення немає: авторизовані для нього платежі потрібно захопити в панелі KOMOJU; до того замовлення очікує.

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

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

Pending payment: покупця направлено до KOMOJU, він ще не заплатив або KOMOJU ще не підтвердив платіж.

Processing or Completed: KOMOJU підтвердив платіж. WooCommerce задає звичайний статус оплаченого замовлення. Примітка містить ID платежу KOMOJU, спосіб оплати й підтвердження (вебхук чи повернення). ID транзакції — ID платежу KOMOJU; на екрані замовлення він веде до платежу в панелі KOMOJU.

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

Failed: платіж не вдався. Покупець може повторити спробу.

Cancelled: термін квитанції минув або платіж скасовано.

Refunded: платіж повністю повернено з WooCommerce чи панелі KOMOJU.

Якщо захоплено другий платіж за вже оплачене замовлення, воно повторно не змінюється. Примітка просить повернути дублікат у панелі KOMOJU. Замовлення з поверненням ніколи не відкриваються знову.

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

Відкрийте замовлення, натисніть Refund, введіть суму й натисніть Refund via KOMOJU Payment. Підтримуються повні та часткові повернення. Використовується ключ режиму оплати замовлення, тому його секретний ключ має бути заданий. Плагін спочатку перевіряє платіж у KOMOJU і відхиляє повернення понад доступний залишок. Якщо автоматичне повернення неможливе (деякі способи, наприклад konbini, потребують банківських реквізитів покупця), показується помилка KOMOJU і нічого не реєструється: виконайте повернення в панелі KOMOJU. Воно вважається виконаним лише після підтвердження KOMOJU. Успішне повернення додається до приміток.

Для платежів, конвертованих KOMOJU в іншу валюту (наприклад konbini у JPY для замовлення EUR), з WooCommerce можливе лише повне повернення. Часткові виконуйте в панелі KOMOJU.

Повернення з панелі KOMOJU надходять вебхуком і автоматично реєструються у WooCommerce. Повне повернення задає статус Повернено. Часткові з панелі для конвертованих платежів лише зазначаються в замовленні: внесіть відповідну суму у WooCommerce через "Refund manually".

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

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

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

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

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

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

KOMOJU не відображається при оформленні: перевірте активну ліцензію, увімкнення Enable/Disable і секретний ключ режиму: Sandbox Secret Key для sandbox, Live Secret Key для робочого. Валюта має підтримуватися KOMOJU. Налаштування попереджають про відсутнє.

Платіж пройшов, але замовлення Pending payment: вебхук не працює. У панелі KOMOJU перевірте наявність для потрібного режиму, точний URL з налаштувань і вибрані події. Перевірте токен у правильному полі (Live Webhook Secret Token або Sandbox Webhook Secret Token) та WooCommerce > Status > Logs, джерело wcp_komoju_payment. Картки підтверджуються також після повернення покупця, konbini й перекази — лише вебхуком.

Вебхук відповідає Failed to verify KOMOJU webhook signature: секретний токен відсутній чи належить іншому вебхуку. KOMOJU повторює сповіщення.

Вебхук відповідає Mode mismatch, ignored: підписано токеном іншого режиму, ніж оплата замовлення. Використовуйте окремі вебхуки й токени для робочого й тестового режимів.

Вебхук відповідає Order is busy, retry later або Temporary error, retry later: інший запит оновлював замовлення або платіж не вдалося перевірити зараз. KOMOJU повторює сповіщення.

Замовлення On hold: прочитайте примітку. Квитанція чекає оплати, платіж — захоплення в панелі KOMOJU, сума чи валюта не збіглися або платіж прийшов після скасування.

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

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

Розробники можуть змінити валюти фільтром komoju_p_supported_currencies і сесію, наприклад способи оплати, фільтром komoju_p_session_params.

Видалення

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

KOMOJU — торговельна марка відповідного власника. Цей плагін не пов’язаний із KOMOJU та не схвалений KOMOJU.