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 точно збігається з 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 і не схвалений нею.