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.

Способ оплаты работает в классическом оформлении заказа, в блоке «Оформление заказа» и на странице 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.