VibeFox KOMOJU for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старые версии PHP.

Учётная запись KOMOJU: нужны секретный ключ (sk_live_... и для тестовой среды sk_test_...) и секретный токен вебхука, созданного в панели KOMOJU (см. Настройка). Публичный ключ (publishable key) не требуется. KOMOJU должен иметь доступ к URL вебхука вашего магазина.

Валюта корзины: JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD или VND. Для корзин в других валютах способ оплаты скрывается.

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

Установка

1. В бэк-офисе перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По окончании загрузки нажмите Configure или позже найдите VibeFox KOMOJU Payment в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в License key в блоке лицензии вверху страницы настроек и нажмите Activate (см. Лицензионный ключ).

4. В панели KOMOJU добавьте вебхук с URL и событиями из раздела Webhook URL и скопируйте его секретный токен (см. Настройка).

5. Введите секретный ключ рабочей среды и секретный токен вебхука рабочей среды, а также тестовые значения для тестовой среды. Включите Enable/Disable и нажмите Save.

При установке модуль создаёт два статуса заказа: Awaiting KOMOJU payment и KOMOJU payment on hold. PrestaShop привязывает новый платёжный модуль только к странам, активным на тот момент: страну, которую вы включите позже, нужно отметить для модуля в Payment > Preferences. Там же можно ограничить валюты и группы покупателей.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox KOMOJU Payment > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает KOMOJU Sandbox Mode is enabled., пока включена тестовая среда. Она предупреждает, если в текущей среде нет секретного ключа (тогда способ оплаты скрывается при оформлении заказа) или секретного токена вебхука (тогда уведомления KOMOJU отклоняются, и платежи konbini и банковским переводом никогда не подтверждаются), а также если KOMOJU не поддерживает валюту магазина по умолчанию (тогда способ оплаты скрывается для корзин в этой валюте).

Оплата KOMOJU

Enable/Disable: Enable KOMOJU Payment Gateway включает или выключает способ оплаты. По умолчанию: выключено.

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 вебхука, указанный в разделе Webhook 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). По умолчанию: выключено. Пока режим включён, оформление заказа показывает Test mode над описанием.

Sandbox Secret Key: ваш секретный тестовый ключ KOMOJU. Он начинается с sk_test_.

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

Сохранённые ключи и токены больше не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Очистить сохранённые секреты: отметьте ключ или токен и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

URL вебхука

Вебхук сообщает вашему магазину о платежах, включая отложенные платежи konbini и банковским переводом. В панели KOMOJU в разделе Settings > Webhooks добавьте URL, указанный в этом разделе, для рабочей и для тестовой среды. При понятных URL он выглядит так: https://your-shop/module/wcp_komoju_payment/webhook, возможно, с кодом языка, например /en/. Скопируйте URL точно так, как его показывают настройки. Затем скопируйте секретный токен каждого вебхука в поле Live Webhook Secret Token или Sandbox Webhook Secret Token.

Выберите эти события (они также перечислены в этом разделе):

payment.authorized: выдана платёжная квитанция (konbini, банковский перевод) или платёж авторизован. Заказ создаётся в статусе Awaiting KOMOJU payment.

payment.captured: платёж завершён. Заказ отмечается оплаченным после проверки суммы и валюты.

payment.expired: срок платёжной квитанции истёк. Заказ отменяется.

payment.cancelled: платёж отменён. Заказ отменяется.

payment.failed: платёж не прошёл. Существующий заказ переходит в Payment error; без заказа ничего не создаётся.

payment.refund.created: выполнен возврат, например в панели KOMOJU. Он записывается в заказ.

payment.refunded: платёж возвращён. Возврат записывается в заказ.

События истечения срока, отмены и ошибки меняют заказ только для его текущего платежа, поэтому платёж из более ранней попытки не может отменить заказ, который оплачивается другим способом. Вебхуки без действительной подписи отклоняются. Вебхуки, подписанные любым из двух секретных токенов, принимаются, но только для платежей той же среды. Без вебхука платежи картой по-прежнему подтверждаются при возвращении покупателя в магазин, но платежи konbini и банковским переводом не подтверждаются никогда.

Дополнительно

Invoice Prefix: префикс номеров заказов, отправляемых в KOMOJU, за которым следует номер корзины. Если вы используете несколько магазинов с одной учётной записью KOMOJU, сделайте его уникальным для каждого магазина. По умолчанию: PS-.

Enable Logging: записывает события KOMOJU и вызовы API в файл logs/komoju_p_debug.log.php в папке модуля. Файл нельзя открыть из веб-браузера. Ключи и данные покупателей не записываются. Ошибки и предупреждения записываются всегда. По умолчанию: выключено.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete data on uninstall: если включено, при удалении модуля удаляются настройки шлюза и журнал. Заказы, транзакции и возвраты KOMOJU и статусы заказов всегда сохраняются, поэтому старые заказы можно подтвердить и вернуть средства после повторной установки. По умолчанию: выключено.

Оформление заказа

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию KOMOJU Payment) и подтверждает выбор. Модуль создаёт платёжную сессию KOMOJU на сумму корзины в валюте корзины и отправляет покупателя на платёжную страницу KOMOJU. Адрес электронной почты, имя, платёжный и адрес доставки, а также заказанные товары передаются в KOMOJU. Страница показывается на японском, английском или корейском языке в зависимости от языка корзины (для других языков — английский). Там покупатель выбирает способ оплаты. Доступные способы зависят от вашей учётной записи KOMOJU и валюты корзины. На этом этапе заказа ещё нет.

После оплаты покупатель возвращается в ваш магазин. Модуль читает платёжную сессию через API KOMOJU с ключом среды платежа. Заказ отмечается оплаченным только после подтверждения KOMOJU: подписанным вебхуком или чтением сессии при возвращении покупателя. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением Your payment with KOMOJU has been received. Если в этот момент KOMOJU недоступен, на странице Payment confirmation появляется сообщение 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. и кнопка Check again.

При платежах konbini и банковским переводом покупатель получает платёжную квитанцию. Заказ создаётся в статусе Awaiting KOMOJU payment, а страница подтверждения сообщает покупателю, что нужно завершить оплату по инструкции KOMOJU (например, в магазине у дома или банковским переводом). Заказ переходит в статус Payment accepted, когда покупатель оплачивает и KOMOJU отправляет вебхук. Если квитанция истекает или платёж позже не проходит, страница подтверждения показывает Your KOMOJU payment was not completed. Please contact us about this order.

Если платёж не завершён, покупатель возвращается к оформлению заказа с сообщением The payment was not completed. You can try again or choose another payment method. Корзина сохраняется. Новая попытка использует открытую платёжную сессию KOMOJU, если сумма не изменилась. Сессия со старой суммой отменяется в 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. Техническая причина записывается в журнал.

Если купон в корзине перестаёт действовать между оплатой и её подтверждением, PrestaShop удаляет его из заказа. Заказ тогда переходит в статус KOMOJU payment on hold с примечанием, потому что покупатель оплатил цену со скидкой.

Вебхук работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

Модуль не имеет формы карты на вашем сайте, сохранённых карт или подписок. Он не ограничивает способы оплаты: они выбираются на странице KOMOJU. У него нет действия ручного списания: платежи, авторизованные для ручного списания, нужно списать в панели KOMOJU, и заказ до этого остаётся в статусе Awaiting KOMOJU payment.

Заказы и возвраты

Статусы заказа

No order yet: покупатель был отправлен в KOMOJU и не оплатил или KOMOJU ещё не подтвердил платёж. Существует только корзина.

Payment accepted: KOMOJU подтвердил платёж. Платёж записывается с ID платежа KOMOJU как ID транзакции, а примечание показывает ID платежа, способ оплаты и способ подтверждения (вебхук или возвращение).

Awaiting KOMOJU payment: выдана квитанция konbini или банковского перевода и ожидается оплата, или платёж ожидает списания в панели KOMOJU.

KOMOJU payment on hold: KOMOJU сообщил сумму или валюту, отличающиеся от суммы заказа (например, корзина была изменена после начала платежа), купон был удалён или платёж был списан после отмены заказа. Примечание объясняет это. Проверьте заказ и выполните его или верните платёж.

Canceled: срок платёжной квитанции истёк или платёж был отменён.

Payment error: платёж по существующему заказу не прошёл.

Refunded: платёж полностью возвращён со страницы заказа или в панели KOMOJU.

Если для уже оплаченного заказа списан второй платёж, заказ не меняется. Примечание просит вернуть его в панели KOMOJU, если это дубликат. Возвращённые заказы никогда не открываются снова.

Блок платежа KOMOJU

На странице заказа показан блок KOMOJU payment с ID платежа KOMOJU (ссылка на платёж в панели KOMOJU) и способом оплаты, сессией, номером заказа в KOMOJU, статусом, оплаченной суммой и возвращённой суммой, метка Test mode для тестовых платежей, история возвратов и KOMOJU notes заказа.

Возвраты

В блоке KOMOJU payment введите сумму (невозвращённая сумма подставляется автоматически), при необходимости причину, и нажмите Refund via KOMOJU. Подтвердите вопрос Refund this amount through KOMOJU? This cannot be undone. Поддерживаются полные и частичные возвраты. Вам нужно право редактировать заказы. Возвраты ограничены суммой, которую KOMOJU фактически списал, поэтому после расхождения суммы можно вернуть не больше того, что заплатил покупатель, а не сумму заказа. Возврат отправляется с ключом среды, в которой был сделан платёж, поэтому должен быть задан секретный ключ этой среды. Модуль сначала проверяет платёж в KOMOJU и отказывает в возвратах сверх ещё возвратного остатка. Если KOMOJU не может вернуть платёж автоматически (для некоторых способов, например konbini, нужны банковские реквизиты покупателя), показывается сообщение об ошибке KOMOJU и ничего не записывается: такие возвраты выполняйте в панели KOMOJU. Возврат считается выполненным только после подтверждения KOMOJU. Успешный возврат добавляется в историю возвратов и примечания. Полный возврат переводит заказ в Refunded. Частичный возврат не меняет статус. Возвраты доступны после того, как KOMOJU списал платёж.

Для платежей, которые KOMOJU конвертировал в другую валюту (например, konbini в JPY для корзины в EUR), из PrestaShop возможен только полный возврат. Частичные возвраты выполняйте в панели KOMOJU.

Модуль не создаёт кредитных нот. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через KOMOJU.

Возвраты, сделанные в панели KOMOJU, приходят через вебхук и добавляются в историю возвратов с примечанием. Когда возвращён весь платёж, заказ переводится в Refunded. Частичные возвраты, сделанные в панели для платежей, конвертированных в другую валюту, только отмечаются в заказе: внесите соответствующую сумму в PrestaShop вручную (кредитная нота).

Лицензионный ключ

Модуль работает с лицензионным ключом VibeFox, полученным на vibefox.net. Блок лицензии License — VibeFox KOMOJU Payment — первый блок на странице Modules > Module Manager > VibeFox KOMOJU Payment > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now, чтобы проверить статус повторно, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: presta-payment-komoju и ссылка Manage licenses and domains in your account, которая открывает вашу учётную запись vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока соответствуют языку бэк-офиса (включены английский и русский).

Если ключ не принят, блок указывает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения места для домена в вашей учётной записи нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: на домене основного магазина, в том числе при мультимагазинной конфигурации. Удаление ключа из магазина не освобождает место для домена. Освободите место в своей учётной записи vibefox.net.

Без активного ключа KOMOJU не показывается покупателям при оформлении заказа. Если оплата всё же начата, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, и возвраты работают.

Когда срок лицензии истекает, модуль продолжает работать, но обновления и поддержка требуют продления. Статус автоматически проверяется снова во время работы в бэк-офисе: раз в день в течение первых 14 дней после ввода ключа, затем раз в неделю. Cron-задание не нужно. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

KOMOJU не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён и в текущей среде есть секретный ключ: Sandbox Secret Key в тестовой среде, Live Secret Key в рабочей. Валюта корзины должна поддерживаться KOMOJU. Страница настроек показывает предупреждение, если чего-то не хватает. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: вебхук не работает. В панели KOMOJU проверьте, что вебхук существует для используемой среды, что его URL точно совпадает с указанным в разделе Webhook URL и что выбраны события. Проверьте, что его секретный токен находится в нужном поле (Live Webhook Secret Token или Sandbox Webhook Secret Token), и посмотрите поле Log на странице модуля. Платежи картой подтверждаются и при возвращении покупателя в магазин, а платежи konbini и банковским переводом подтверждаются только вебхуком.

Вебхук отвечает Failed to verify KOMOJU webhook signature.: секретный токен отсутствует или принадлежит другому вебхуку. KOMOJU повторяет уведомление.

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

Вебхук отвечает Order is busy, retry later. или Temporary error, retry later.: заказ в этот момент обновлял другой запрос, заказ не удалось создать (например, модуль отключён) или платёж не удалось проверить. KOMOJU повторяет уведомление. Причина указана в журнале.

URL вебхука показывает ошибку в браузере: это нормально. URL принимает только подписанные запросы от KOMOJU.

Заказ в статусе KOMOJU payment on hold или Awaiting KOMOJU payment: прочитайте KOMOJU notes в блоке заказа. Квитанция ждёт оплаты, платёж ждёт списания в панели KOMOJU, сумма или валюта не совпали, купон был удалён или платёж пришёл после отмены заказа.

Возврат не выполняется: прочитайте сообщение. Возможно, отсутствует секретный ключ среды, в которой был сделан платёж, платёж нельзя вернуть автоматически (верните его в панели KOMOJU), KOMOJU не знает платёж с настроенным ключом или для конвертированного платежа возможен только полный возврат.

Разработчики могут изменить список валют с помощью хука actionKomojuPSupportedCurrencies, а платёжную сессию, например способы оплаты, — с помощью хука actionKomojuPSessionParams.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox KOMOJU Payment и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete data on uninstall включено, настройки шлюза и журнал удаляются. Если выключено, все настройки сохраняются для будущей повторной установки. Транзакции и возвраты KOMOJU и статусы заказов Awaiting KOMOJU payment и KOMOJU payment on hold всегда сохраняются, поэтому старые заказы можно подтвердить и вернуть средства после повторной установки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

KOMOJU — товарный знак его правообладателя. Этот модуль не связан с KOMOJU и не одобрен им.