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. В панели администратора перейдите в 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) в качестве ID транзакции, а заметка показывает сумму, способ оплаты, референс, транзакцию и режим.

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), ID транзакции и референсом Flutterwave, режимом, статусом и способом оплаты, суммой оплаты и возврата, значком Test mode для тестовых платежей, историей возвратов и Flutterwave notes заказа.

Возвраты

В блоке Flutterwave payment введите сумму (по умолчанию подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Flutterwave. Подтвердите вопрос Refund this amount through Flutterwave? This cannot be undone. Поддерживаются полные и частичные возвраты. Вам нужно право редактировать заказы; доступ к разделам модулей не нужен. Возвраты выполняются на сумму и в валюте, которые списал Flutterwave, поэтому после расхождения суммы или валюты вы можете вернуть не больше того, что покупатель фактически заплатил, а не сумму заказа. Возврат отправляется с секретным ключом того режима, в котором был выполнен платёж (тестовый или рабочий), поэтому этот ключ должен быть задан. Если Flutterwave отклоняет возврат, блок показывает ошибку, и возврат не регистрируется. Успешный возврат добавляется в историю возвратов и заметки с ID возврата и статусом (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 сохраняются всегда, поэтому заказы, оплаченные ранее, можно вернуть и после переустановки. Существующие заказы сохраняют свои заметки о платежах и ID транзакций.

Flutterwave является товарным знаком его владельца. Модуль не связан с Flutterwave и не одобрен компанией Flutterwave.