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

Вимоги

PrestaShop: 8.0–9.x.

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

Обліковий запис Flutterwave: потрібні секретні ключі вашого облікового запису Flutterwave з панелі Flutterwave, розділ Settings, API keys: FLWSECK_TEST-… для тестового режиму та FLWSECK-… для робочого режиму. Використовуються лише секретні ключі. Публічні ключі та ключі шифрування не потрібні. Також ви налаштовуєте вебхук із секретним хешем на свій вибір (див. Налаштування).

Валюти: кошик завжди оплачується у валюті кошика. Модуль сам не обмежує країни та валюти; Flutterwave покаже помилку, якщо ваш обліковий запис не підтримує валюту. Ви можете обмежити валюти, країни та групи клієнтів у розділі Payment > Preferences.

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

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

1. У back office перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

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

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

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

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

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

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

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Flutterwave Payment > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує Live mode: real payments are accepted. або Test mode: no real money is charged. Вона попереджає, коли секретний ключ поточного режиму порожній, коли в полі робочого ключа в робочому режимі міститься тестовий ключ (FLWSECK_TEST-…), або коли в полі тестового ключа в тестовому режимі міститься робочий ключ (FLWSECK-…); тоді спосіб оплати приховується на етапі оформлення, доки проблему не буде виправлено. Вона також попереджає, коли секретний хеш вебхука не задано: вебхуки тоді відхиляються, а платежі підтверджуються лише тоді, коли покупець повертається до вашого магазину. У заголовку першого розділу показано поточний режим: TEST або LIVE.

Flutterwave

Enable/Disable: Enable Flutterwave Payment вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

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

Description: текст, який покупці бачать під способом оплати під час оформлення. За замовчуванням: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.

Ключі API

Скопіюйте секретні ключі з панелі Flutterwave, розділ Settings, API keys (у цьому розділі є посилання). Тестовий і робочий режими мають різні ключі.

Live mode: приймати реальні платежі. Вимкніть, щоб працювати в тестовому режимі. Тестовий режим використовує тестовий секретний ключ, і реальні кошти не списуються. Робочий режим використовує робочий секретний ключ. За замовчуванням: вимкнено (тестовий режим). Поки тестовий режим увімкнено, покупці бачать під способом оплати TEST MODE - no real payments will be processed.

Test Secret Key: ваш тестовий секретний ключ Flutterwave (FLWSECK_TEST-...).

Live Secret Key: ваш робочий секретний ключ Flutterwave (FLWSECK-...).

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

Webhook

Вебхук підтверджує платежі, навіть якщо покупець не повертається до вашого магазину. На панелі Flutterwave, розділ Settings, Webhooks, введіть URL, який показано в цьому розділі в полі Webhook URL, та секретний хеш на свій вибір, для тестового та для робочого режиму. З дружніми URL адреса має вигляд https://your-shop/module/wcp_flutterwave_payment/webhook, можливо з кодом мови, наприклад /en/. Скопіюйте URL точно так, як його показують налаштування. Модуль реагує на таку подію:

Інші події ігноруються.

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

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

Оплата

Payment Options: способи оплати, розділені комами, для показу на сторінці Flutterwave, наприклад card, banktransfer, ussd, mobilemoney. Залиште порожнім, щоб показувати всі способи, увімкнені у вашому обліковому записі. Список очищується під час збереження (малі літери, без дублікатів).

Autocomplete Orders: оплачені замовлення отримують статус Delivered замість Payment accepted, з однією зміною статусу. За замовчуванням: вимкнено.

Додатково

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

Log: показує розмір журналу та його останні записи. Натисніть Clear log, щоб очистити його.

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Flutterwave) і підтверджує вибір. Потрібна дійсна адреса електронної пошти. Модуль створює платіж Flutterwave на суму кошика у валюті кошика, із адресою електронної пошти покупця, телефоном і ім'ям з адреси для рахунку, назвою та логотипом вашого магазину, і надсилає покупця на сторінку оплати Flutterwave. Там покупець платить одним із способів, увімкнених у вашому обліковому записі (або перелічених у Payment Options). На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Flutterwave: через вебхук або через перевірку на сервері, коли покупець повертається. Тоді замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення. Якщо платіж ще очікує, наприклад банківський переказ, USSD або мобільні гроші, замовлення створюється у статусі Awaiting Flutterwave payment, а на сторінці з'являється повідомлення Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. Якщо замовлення відкладено на перевірку, наприклад тому, що сплачена сума не збігається з кошиком, сторінка показує Your payment was received and your order is being reviewed. We will contact you if anything is needed. Якщо відкладений платіж згодом не вдався і покупець знову відкриває сторінку підтвердження, вона показує Your Flutterwave payment was not completed. Please contact us about this order.

Якщо Flutterwave недоступна, коли покупець повертається, на сторінці Payment confirmation буде написано Your payment is being confirmed by Flutterwave. Your order will be created as soon as it is confirmed — please do not pay again. з кнопками Check again і Back to checkout. Вебхук створює замовлення, щойно його отримає.

Якщо платіж відхилено, покупець повертається до оформлення з повідомленням Your payment was declined. You can try again or choose another payment method. Якщо покупець скасовує платіж на сторінці Flutterwave, повідомлення: Payment was cancelled. You can try again or choose another payment method. Якщо платіж не було завершено, повідомлення: The payment was not completed. You can try again or choose another payment method. Кошик зберігається, і покупець може оплатити знову. Кожна спроба має власний референс, а старе платіжне посилання, оплачене пізніше, також приймається.

Якщо Flutterwave не може розпочати платіж, покупець залишається на оформленні з коротким повідомленням, наприклад Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method. Технічна причина записується до журналу.

Якщо кошик змінюється між оплатою та її підтвердженням, наприклад в іншій вкладці браузера, суми більше не збігаються, і замовлення переходить у статус Flutterwave payment on hold з приміткою.

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

Модуль приймає лише разові платежі. Він не має вбудованої чи модальної форми оплати на вашому сайті, збережених карток, підписок, розділених платежів або планів оплати. Посилання на розміщену оплату не можна скасувати через API Flutterwave, тому старе посилання на оплату кошика все ще може бути оплачене.

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

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

Замовлення ще немає: покупця перенаправлено на Flutterwave, і він ще не платив, або Flutterwave ще не підтвердила платіж. Існує лише кошик.

Payment accepted or Delivered: платіж підтверджено. Delivered використовується, коли Autocomplete Orders увімкнено. Платіж записується з референсом Flutterwave (flw_ref) як ідентифікатор транзакції, а примітка показує суму, спосіб оплати, референс, транзакцію та режим.

Awaiting Flutterwave payment: покупець повернувся, поки платіж ще очікував на підтвердження у Flutterwave. Замовлення переходить у статус оплаченого, коли Flutterwave підтверджує платіж.

Flutterwave payment on hold: перевірена сума або валюта не збіглися з кошиком, або платіж надійшов після того, як замовлення було скасовано. Платіж записується з фактично сплаченою сумою (а не з сумою, яку Flutterwave списала в іншій валюті). Примітка пояснює це. Опрацюйте замовлення або поверніть кошти за платіж. Повторний вебхук ніколи не відкриває знову повернене чи скасоване замовлення.

Payment error: Flutterwave повідомила, що остання спроба оплати замовлення в очікуванні не вдалася або була скасована. Примітка показує причину.

Canceled: встановлюєте ви. Якщо Flutterwave згодом повідомить про платіж за скасоване замовлення, замовлення переходить у статус Flutterwave payment on hold (див. вище).

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

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

Блок Flutterwave payment

На сторінці замовлення відображається блок Flutterwave payment з референсом (tx_ref), ідентифікатором транзакції та референсом Flutterwave, режимом, статусом і способом оплати, сплаченою та поверненою сумою, позначкою Test mode для тестових платежів, історією повернень і Flutterwave notes замовлення.

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

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

Модуль не створює кредитових нот. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають кошти через Flutterwave.

Повернення, оформлені на панелі Flutterwave, не синхронізуються з PrestaShop. За потреби оновіть статус замовлення вручну.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Flutterwave Payment є першим блоком у Modules > Module Manager > VibeFox Flutterwave Payment > Configure, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ замаскованим, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче розташовані рядок Product: presta-payment-flutterwave і посилання 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.

Без активного ключа Flutterwave не показується покупцям на етапі оформлення. Якщо платіж все одно розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви ввійшли в бек-офіс, тож спосіб оплати приховано і для вас: ви можете налаштувати модуль до купівлі ключа, але не можете перевірити його на етапі оформлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: платежі, які вже розпочато, і далі підтверджуються, а повернення працюють.

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

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

Flutterwave не з'являється під час оформлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, а секретний ключ поточного режиму заповнений і відповідає режиму: тестовий ключ (FLWSECK_TEST-…) у тестовому режимі, робочий ключ (FLWSECK-…) у робочому режимі. Інакше сторінка налаштувань показує попередження. У розділі Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: вебхук не працює. На панелі Flutterwave перевірте, що URL вебхука точно такий, як показано в полі Webhook URL, у режимі, яким ви користуєтесь (тестовому або робочому), і що його секретний хеш збігається зі значенням Secret Hash у модулі. Банківські перекази, USSD і мобільні гроші, що очікують, залишаються в очікуванні, доки Flutterwave їх не підтвердить. Замовлення також створюється, коли покупець повертається до магазину після оплати. Увімкніть Debug log і перегляньте поле Log на сторінці модуля.

Вебхук відповідає Invalid hash або Secret hash not configured: секретний хеш на панелі Flutterwave відрізняється від того, що в модулі, або в модулі його немає. Введіть однакове значення в обох місцях.

Вебхук відповідає Verification failed, Busy, retry later або Order could not be created, retry later: не вдалося зв'язатися з Flutterwave для перевірки платежу, транзакція ще не видна, кошик у цей момент оброблявся іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). Flutterwave повторить вебхук. Журнал показує причину.

URL вебхука в браузері показує Empty body: це нормально. URL приймає лише вебхуки від Flutterwave.

Покупець бачить Payment gateway is not properly configured: секретний ключ поточного режиму відсутній або належить до іншого режиму.

Покупець бачить We could not match this payment to an order: посилання повернення містить референс, який не належить кошику покупця. Якщо з покупця списали кошти, знайдіть платіж на панелі Flutterwave.

Flutterwave показує помилку на своїй сторінці або покупець бачить Flutterwave could not start the payment: ваш обліковий запис Flutterwave може не підтримувати валюту кошика або вибрані способи оплати.

Замовлення має статус Flutterwave payment on hold після оплати: прочитайте примітки в блоці Flutterwave payment (див. Статуси замовлення), потім опрацюйте замовлення або поверніть кошти за платіж.

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

Повернення відповідає Another operation on this payment is running: у цей момент надсилалося інше повернення того самого замовлення. Зачекайте трохи, перевірте історію повернень і за потреби спробуйте знову.

Для розробників: README модуля перелічує хуки actionWcpFlutterwavePaymentRequest (дані, що надсилаються до Flutterwave) та actionWcpFlutterwaveCurrencyDecimals (точність валюти).

Видалення

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

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