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

Вимоги

WordPress: 5.8 або новіша версія.

WooCommerce: 7.0 або новіша версія, встановлено й увімкнено. Без WooCommerce плагін не активується.

PHP: 8.0 або новіша версія. На старіших версіях PHP плагін не активується.

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

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

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

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна й натисніть Install Now. Також можна завантажити папку wcp_flutterwave_payment до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Flutterwave > Manage, або натисніть Settings під назвою плагіна на сторінці плагінів.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії вгорі сторінки й натисніть Activate.

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

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

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

Усі налаштування розміщені на одній сторінці: WooCommerce > Settings > Payments > Flutterwave. Над полями сторінка показує Live mode: real payments are accepted. або Test mode: no real money is charged. Вона попереджає, якщо секретний ключ поточного режиму порожній, поле робочого ключа містить тестовий ключ (FLWSECK_TEST-…) у робочому режимі або поле тестового ключа містить робочий ключ (FLWSECK-…) у тестовому; спосіб оплати приховується під час оформлення замовлення, доки це не виправлено. Також з'являється попередження, якщо не задано секретний хеш вебхука: вебхуки відхиляються, а платежі підтверджуються лише після повернення покупця до магазину. У списку способів оплати Flutterwave позначається як такий, що потребує налаштування, доки поточний режим не матиме секретного ключа, а в тестовому режимі відображає відповідний значок.

Загальні

Enable/Disable: Enable Flutterwave Payment вмикає або вимикає спосіб оплати. Типово: off.

Title: назва способу оплати, яку покупці бачать під час оформлення замовлення. Типово: Flutterwave.

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

Ключі API

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

Live mode: Accept real payments (uncheck for test mode). Тестовий режим використовує тестовий секретний ключ і не стягує реальних грошей. Робочий режим використовує робочий секретний ключ. Типово: off (тестовий режим).

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

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

Вебхук

Вебхук підтверджує платежі, навіть якщо покупець не повертається до магазину. У панелі Flutterwave в розділі Settings, Webhooks введіть Webhook URL із цього розділу та секретний хеш на ваш вибір у тестовому й робочому режимах. URL має вигляд https://your-site/wc-api/flw_p_webhook/. Плагін реагує на цю подію:

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

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

Оплата

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

Autocomplete Orders: Automatically mark orders as completed after successful payment. Якщо ввімкнено, після оплати замовлення отримують статус «Виконано» замість «В обробці» за одну зміну статусу. Типово: off.

Додатково

Debug log: Log Flutterwave API events for debugging у WooCommerce > Status > Logs, джерело wcp_flutterwave_payment. Помилки завжди записуються. Ключі та дані покупців ніколи не записуються. Типово: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Вимкнення плагіна ніколи нічого не видаляє. Платіжні дані, збережені в замовленнях, завжди залишаються. Типово: off.

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

Покупець вибирає спосіб оплати (типово Flutterwave) й оформлює замовлення. У тестовому режимі сторінка оформлення показує TEST MODE - no real payments will be processed. Потрібна дійсна платіжна адреса електронної пошти. Плагін створює платіж Flutterwave на повну суму замовлення в його валюті з електронною поштою, телефоном та ім'ям покупця, назвою й логотипом вашого сайту та спрямовує покупця на сторінку оплати Flutterwave. Там покупець платить одним зі способів, увімкнених у вашому обліковому записі (або перелічених у Payment Options).

Після оплати покупець повертається до магазину. Замовлення позначається оплаченим лише після підтвердження Flutterwave: через вебхук або серверну перевірку під час повернення покупця. Якщо платіж ще не підтверджено, наприклад очікує банківський переказ, платіж USSD чи мобільними грошима, сторінка отриманого замовлення показує 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.

Якщо платіж відхилено, покупець повертається до оформлення замовлення (або на сторінку Pay for order) з повідомленням 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.

Спосіб оплати працює в класичному оформленні замовлення, у блоці Checkout та на сторінці Pay for order. Він сумісний з WooCommerce High-Performance Order Storage (HPOS). Тексти для покупців перекладено французькою.

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

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

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

Pending payment: покупця спрямовано до Flutterwave, і він ще не заплатив, або платіж досі очікує у Flutterwave.

Processing or Completed: платіж підтверджено. Статус «Виконано» використовується, коли Autocomplete Orders увімкнено (замовлення лише з віртуальними завантажуваними товарами також отримують статус «Виконано», що є типовою поведінкою WooCommerce). Нотатка до замовлення показує суму, спосіб оплати, ідентифікатор Flutterwave, транзакцію та режим. Ідентифікатор транзакції замовлення — ідентифікатор платежу Flutterwave.

On hold after payment: перевірена сума або валюта не відповідала замовленню, або платіж надійшов після скасування замовлення. Нотатка пояснює причину. Виконайте замовлення або поверніть кошти. Повторний вебхук ніколи не відкриває знову замовлення з поверненням коштів або скасоване замовлення.

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

Cancelled: покупець скасував оплату на сторінці Flutterwave після оформлення замовлення, або замовлення скасували ви чи WooCommerce після завершення строку резервування запасів.

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

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

Відкрийте замовлення, натисніть Refund, введіть суму й натисніть Refund via Flutterwave. Підтримуються повні та часткові повернення. Повернення надсилається із секретним ключем режиму, в якому було здійснено платіж (тестового або робочого), тому цей ключ має бути заданий. Якщо Flutterwave відхиляє повернення, WooCommerce показує помилку, а повернення не реєструється. Успішне повернення додається до нотаток замовлення з ідентифікатором і статусом повернення (завершено або ініційовано зі статусом, повідомленим Flutterwave).

Повернення коштів з панелі Flutterwave не синхронізуються з WooCommerce. За потреби створіть ручне повернення у WooCommerce без Refund via Flutterwave.

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташований угорі WooCommerce > Settings > Payments > Flutterwave. Вставте ключ у License key та натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, і ваш домен. Використовуйте Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа із цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

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

Без активного ключа Flutterwave не показується покупцям під час оформлення замовлення. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Менеджери магазину, які увійшли в систему, й далі бачать спосіб оплати з позначкою (unlicensed — visible to admins only), щоб ви могли налаштувати й перевірити плагін до придбання ключа. Нагадування з'являється на сторінці плагінів та сторінках WooCommerce. Наявні замовлення не зачіпаються: розпочаті платежі й далі підтверджуються, а повернення працюють.

Коли ліцензія закінчується, плагін продовжує працювати, але оновлення та підтримка потребують поновлення. Статус автоматично перевіряється знову у фоновому режимі.

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

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

Платіж пройшов, але замовлення залишається Pending payment: вебхук не працює. У панелі Flutterwave перевірте, що URL вебхука точно відповідає показаному в налаштуваннях для використовуваного режиму (тестового чи робочого), а його секретний хеш збігається з Secret Hash у плагіні. Банківські перекази, USSD та мобільні гроші, які очікують, залишаються в очікуванні до підтвердження Flutterwave. Увімкніть Debug log і перегляньте WooCommerce > Status > Logs, джерело wcp_flutterwave_payment.

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

Вебхук відповідає Verification failed або Busy, retry later: не вдалося зв'язатися з Flutterwave для перевірки платежу, транзакція ще не видима або замовлення оновлювалося іншим запитом. Flutterwave повторює вебхук.

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

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

Flutterwave показує помилку на своїй сторінці: ваш обліковий запис Flutterwave може не підтримувати валюту замовлення або вибрані способи оплати.

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

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

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть слот в обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати з останнім відомим статусом.

Для розробників документація плагіна містить фільтри flw_p_payment_request (дані, надіслані до Flutterwave), flw_p_currency_decimals (точність валюти) та flw_p_icon (значок під час оформлення замовлення).

Видалення

Після вимкнення плагіна всі дані зберігаються. Щоб видалити його, вимкніть і видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна видаляються завжди. Налаштування шлюзу та журнали видаляються лише за ввімкненої опції Delete data on uninstall. Інакше вони залишаються для подальшого перевстановлення. Дані Flutterwave в замовленнях завжди зберігаються. Наявні замовлення зберігають платіжні нотатки та ідентифікатори транзакцій.

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