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

Вимоги

PrestaShop: від 8.0 до 9.x.

PHP: 8.0 або новіша. Модуль не встановлюється на старіших версіях PHP.

HTTPS: поля картки розміщені на сторінці оформлення замовлення, тож вона має відкриватися через HTTPS. Дані картки все одно ніколи не потрапляють на ваш сервер. Omise надсилає вебхуки лише на адреси HTTPS, а сторінка 3-D Secure банку також має бути адресою 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. В адмін-панелі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Omise Payment у списку модулів і натисніть Configure.

3. Введіть ліцензійний ключ VibeFox у поле License key блоку ліцензії вгорі сторінки Configure і натисніть Activate (див. Ліцензійний ключ).

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

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

Під час встановлення модуль створює три статуси замовлень: Omise payment authorized, Omise payment on hold і Awaiting Omise payment. Спосіб оплати пропонується для країн, які активні на момент встановлення. Якщо ви пізніше активуєте більше країн, дозвольте модуль і для них у розділі Payment > Preferences, де його також можна обмежити за валютою та групою клієнтів.

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

Усі налаштування розміщені на сторінці модуля: Modules > Module Manager > VibeFox Omise Payment > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує 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 вмикає або вимикає спосіб оплати. За замовчуванням: off.

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

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

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

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

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

Збережені секретні ключі більше не показуються. Поле лишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Clear saved secrets: позначте секретний ключ і натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

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

Webhook URL: адреса вебхука вашого магазину. З дружніми URL вона виглядає так: https://your-shop/module/wcp_omise_payment/webhook. Скопіюйте її точно так, як її показують налаштування, і додайте в панелі Omise в розділі Settings > Webhooks (лише HTTPS). Модуль обробляє такі події (вони також перелічені в цьому розділі):

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

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

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

Додатково

Debug log: записує запити до API та події платежів у logs/omise_p_debug.log.php у папці модуля. Файл не можна прочитати з веб-браузера. Ключі, токени та дані картки ніколи не записуються в журнал. За замовчуванням: off. Поки журнал вимкнено, нічого не записується, зокрема помилки, тож увімкніть його, коли шукаєте проблему.

Log: показує розмір і останні записи журналу, а також кнопку очищення.

Delete data on uninstall: якщо увімкнено, під час видалення модуля видаляються налаштування та журнал налагодження. Списання та повернення Omise за замовленнями є історією платежів і завжди зберігаються. За замовчуванням: off.

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

На кроці оплати покупець обирає спосіб оплати (за замовчуванням 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 перетворює картку на одноразовий токен у браузері, використовуючи платіжну адресу з кошика. Поля картки ніколи не надсилаються до вашого магазину. Відсутні або некоректні поля показуються під формою, наприклад Please enter a valid card number.

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

Замовлення позначається оплаченим лише після підтвердження Omise: платіж має бути списаний, а його сума та валюта мають відповідати кошику. Покупець бачить стандартну сторінку підтвердження замовлення з Your card payment has been received. За Authorize only сторінка каже Your card payment has been authorized. The amount will be charged when your order is processed. Якщо Omise досі вважає платіж очікуваним, замовлення створюється у статусі Awaiting Omise payment, а сторінка показує Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. Якщо платіж не вдається підтвердити одразу після 3-D Secure, з'являється сторінка Payment confirmation з текстом We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again. і кнопкою Check again.

Якщо картку відхилено, замовлення не створюється. Покупець лишається на оформленні замовлення з повідомленням Payment failed: і причиною, наприклад недостатньо коштів, невірний код безпеки або відмова банку-емітента картки, і може повторити спробу з тим самим кошиком. Якщо 3-D Secure не пройшов, покупець повертається на оформлення замовлення з причиною; якщо платіж тим часом минув або був анульований, повідомлення: The payment was not completed. Please try again.

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

Вебхук працює, поки магазин перебуває в режимі обслуговування, і не блокується обмеженням за країнами вашого магазину.

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

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

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

No order yet: покупець на 3-D Secure або картку відхилено. Існує лише кошик.

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

Omise payment authorized: картку авторизовано з Authorize only. Використовуйте Capture payment або Void authorization.

Awaiting Omise payment: Omise ще не підтвердив платіж. Вебхук або Sync payment status оновлює замовлення.

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

Payment error: платіж, що очікував, пізніше не пройшов. Оплачене замовлення ніколи не знижується через пізнішу подію невдачі.

Canceled: термін платежу минув або авторизацію анульовано.

Refunded: платіж повністю повернено через модуль.

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

Блок оплати Omise

На сторінці замовлення показано блок Omise payment з ID списання, дією оплати, статусом списання, брендом і останніми цифрами картки, сумами списано, замовлення та повернено, значком Test mode для тестових платежів та історією повернень. Кнопки блоку потребують права редагувати замовлення та секретного ключа того режиму, у якому було здійснено оплату. Доступ до сторінок модулів не потрібен. Результат кожної дії показується у верхній частині блоку.

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

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

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

Повернення

У блоці Omise payment введіть суму (підставляється сума, яка ще не повернута), за бажанням причину, і натисніть Refund via Omise. Підтвердіть питання Refund this amount through Omise? This cannot be undone. Підтримуються повне та часткове повернення. Повернення виконуються в сумі та валюті, які списав Omise, тож після невідповідності суми або валюти можна повернути лише до суми, яку покупець фактично сплатив, а не до суми замовлення. Повернення надсилається в режимі, у якому було здійснено платіж, тож секретний ключ цього режиму має бути заданий. Причина зберігається разом із поверненням в Omise. Успішне повернення додається до історії повернень і нотаток з ID повернення Omise. Повне повернення переводить замовлення у статус Refunded; часткове повернення статус не змінює. Для авторизації, яку ще не списано, можливе лише повне повернення, і воно анулює авторизацію. Якщо Omise відхиляє повернення, блок показує Refund failed. з повідомленням Omise, і жодне повернення не записується.

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

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

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

Якщо ключ не приймається, блок пояснює причину, наприклад Ключ не знайдено, Цей ключ належить іншому продукту, Досягнуто ліміт доменів або Термін дії ліцензії минув із датою. Після зміни адреси магазину або після звільнення слота домену в обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль працює далі з останнім відомим статусом.

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

Без активного ключа спосіб оплати Omise не показується покупцям на сторінці оформлення замовлення. Якщо все ж розпочато платіж, покупець бачить Цей спосіб оплати недоступний. Оберіть інший. Вітрина PrestaShop не знає, що ви ввійшли в адмін-панель, тому спосіб оплати приховується і для вас: модуль можна налаштувати до купівлі ключа, але перевірити його на сторінці оформлення замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: платежі, уже розпочаті, як і раніше підтверджуються, а повернення працюють.

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

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

Omise does not appear at checkout: перевірте, що ліцензія активна, увімкнено Enable/Disable, введено обидва ключі поточного режиму (тестові в тестовому режимі, робочі в інших випадках) і валюта кошика належить до підтримуваних. Сторінка налаштувань показує попередження, якщо ключі не заповнено. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

The payment went through, but no order was created or the order stays Awaiting Omise payment: вебхук не працює. У панелі Omise перевірте, що URL вебхука точно збігається з показаним у Webhook URL і використовує HTTPS. Для наявного замовлення натисніть Sync payment status. Увімкніть Debug log, щоб побачити відповіді вебхука.

Webhook answers Charge ID does not match order or Order not found: списання в події не було створено цим магазином для цього кошика. Нічого не змінюється.

Webhook answers Order is being processed, retry later or Failed to verify charge: кошик у той самий момент було заблоковано іншим запитом, API Omise не вдалося досягти, або секретний ключ режиму платежу відсутній. Omise повторить вебхук.

Webhook answers The order could not be created, retry later: замовлення не вдалося створити, наприклад через те, що модуль вимкнено. Увімкніть Debug log, щоб побачити причину.

The webhook URL shows Method not allowed in the browser: це нормально. URL приймає лише запити від Omise.

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

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

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

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

Order is Omise payment on hold after payment: прочитайте нотатку в замовленні (див. Статуси замовлення), потім виконайте замовлення або поверніть платіж.

Refund fails with a message about the mode: платіж було здійснено в тестовому або робочому режимі, а секретний ключ цього режиму не задано. Введіть його і повторіть спробу.

Partial refund of an authorized order fails: платіж лише авторизовано. Спершу списіть його або поверніть повну суму, щоб анулювати.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Omise Payment і оберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete data on uninstall увімкнено, налаштування та журнал налагодження видаляються. Якщо вимкнено, усі налаштування зберігаються для повторного встановлення. Списання й повернення Omise та статуси замовлень Omise payment authorized, Omise payment on hold і Awaiting Omise payment завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Наявні замовлення зберігають свої платіжні нотатки та ID транзакцій.

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