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. Введите рабочий секретный ключ и секретный токен рабочего вебхука, а также тестовые значения для тестовой среды. Включите Enable/Disable и сохраните.

Настройка

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

Общие настройки

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. В 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, если сумма не изменилась. Сессия со старой суммой отменяется в 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. Подробности добавляются в примечания к заказу и журнал.

Способ оплаты работает в классическом оформлении заказа, блоке «Оформление заказа» и на странице 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 и отклоняет возврат сверх доступной суммы. Если 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 в тестовой, 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.