VibeFox Hubtel for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее с расширением cURL. Без них модуль не установится.

Валюта: только ганский седи (GHS). Способ оплаты скрывается на этапе оформления заказа для других валют. Оставьте количество десятичных знаков для валюты GHS равным 2, так как Hubtel списывает целые песевы.

Аккаунт Hubtel: бизнес-аккаунт Hubtel с API-ключами (API ID и API Key) и номером торгового счёта (POS Sales ID). Ключи находятся в бизнес-панели Hubtel на bo.hubtel.com в разделе Programmable keys.

Белый список IP: Hubtel отвечает на запросы Transaction Status API только с IP-адресов серверов из белого списка. Попросите Hubtel (вашего менеджера или support@hubtel.com) внести в белый список публичный IP-адрес вашего веб-сервера. До этого платежи не могут быть подтверждены, и заказ не создаётся.

Тестовой среды нет: у Hubtel нет публичной песочницы. Все платежи реальные.

Cron: рекомендуется настроить cron-задачу на сервере, которая вызывает cron-URL модуля каждые 5 минут для фоновых проверок платежей (см. раздел Конфигурация).

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

Установка

1. В бэк-офисе перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. После завершения загрузки нажмите Configure или позже найдите VibeFox Hubtel Pay Gateway в списке модулей и нажмите Configure.

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

4. Введите API ID, API Key и номер торгового счёта (POS Sales ID).

5. Попросите службу поддержки Hubtel внести IP вашего сервера в белый список для Transaction Status API.

6. Добавьте cron-URL, показанный на странице Configure, в cron вашего сервера.

7. Включите Enable/Disable и нажмите Save. URL колбэка передаётся в Hubtel с каждым платежом, поэтому в панели Hubtel ничего настраивать не нужно.

При установке модуль создаёт статус заказа Hubtel payment on hold. PrestaShop добавляет новый способ оплаты для всех валют, стран и групп клиентов. Ограничить их можно в разделе Payment > Preferences.

Конфигурация

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure. Каждый раздел имеет собственную кнопку Save, которая сохраняет всю страницу. Над полями страница предупреждает, если не заполнены API ID, API Key или номер торгового счёта, а также если основная валюта магазина не GHS. В обоих случаях Hubtel скрывается на этапе оформления заказа. Также предупреждается, если для валюты GHS используется больше 2 десятичных знаков.

Hubtel

Enable/Disable: Enable Hubtel payments включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое видит покупатель на этапе оформления заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: Mobile Money or card (Hubtel). Обязательно: пустое название выдаёт ошибку Enter a title for the payment method.

Description: текст под способом оплаты на этапе оформления заказа. По умолчанию: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. Вы будете перенаправлены на страницу Hubtel для завершения оплаты.

Учётные данные API Hubtel

Скопируйте API ID и API Key из бизнес-панели Hubtel: bo.hubtel.com > Programmable keys. Номер торгового счёта — это POS Sales ID вашего аккаунта Hubtel. В этом разделе также повторяется уведомление о белом списке IP.

API ID (Client ID): API ID ваших программируемых ключей Hubtel.

API Key (Client Secret): API Key ваших программируемых ключей Hubtel. Храните его в секрете. Сохранённый ключ больше никогда не отображается. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Merchant account number (POS Sales ID): платежи зачисляются на этот аккаунт Hubtel и проверяются по нему.

Clear saved API Key: установите флажок и нажмите Save, чтобы удалить сохранённый API Key. Пустое поле оставляет сохранённое значение.

Подтверждение платежа

Callback URL: колбэк сообщает вашему магазину, что платёж произведён. Этот URL передаётся в Hubtel с каждым платежом, поэтому в панели Hubtel ничего настраивать не нужно. При ЧПУ-адресах он выглядит так: https://your-shop/module/wcp_hubtel_pay/callback, возможно, с кодом языка. URL должен быть доступен из интернета: без парольной защиты и без файрвола, блокирующего Hubtel. Колбэк также работает, когда магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

Колбэки Hubtel не подписаны. Модуль берёт из колбэка только референс платежа; референс должен принадлежать платежу вашего магазина. Статус, сумма и ID транзакции всегда берутся из Hubtel Transaction Status API. Заказ создаётся как оплаченный только после того, как этот API подтвердит платёж и его сумму.

Фоновые проверки платежей (cron): cron-URL с секретным токеном. Вызывайте его каждые 5 минут из cron вашего сервера, например, с помощью curl. Платежи без подтверждения будут автоматически повторно проверены в Hubtel: через 20 минут после того, как покупатель был отправлен в Hubtel, ещё раз через час, если платёж всё ещё не оплачен, и до 5 раз с увеличивающимися интервалами, если связаться с Hubtel не удалось. Храните URL в секрете.

Дополнительно

Debug log: записывает вызовы API и колбэки в logs/hubtel_p_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Ключи и данные покупателей не записываются. Ошибки и предупреждения записываются всегда, даже если эта опция выключена. По умолчанию: выключено.

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

Delete data on uninstall: если включено, при удалении модуля удаляются его настройки и журнал. Данные Hubtel, сохранённые для заказов, и статус заказа Hubtel payment on hold всегда остаются. По умолчанию: выключено.

Оформление заказа

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Mobile Money or card (Hubtel)) и подтверждает выбор. Модуль создаёт платёж Hubtel на сумму корзины в GHS и отправляет покупателя на страницу оплаты Hubtel. Там платёж отображается как Cart #, номер корзины и название вашего магазина. На странице Hubtel покупатель платит через MTN MoMo, Telecel Cash, AirtelTigo Money, картой Visa или Mastercard либо GhQR. На этом этапе заказа ещё нет. Каждое подтверждение на этапе оплаты создаёт новую попытку оплаты с собственным референсом, а более ранние страницы Hubtel для той же корзины остаются доступны для оплаты.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается как оплаченный только после подтверждения Hubtel через Transaction Status API: по колбэку, по проверке при возврате покупателя, по фоновой проверке или по кнопке на странице заказа. Колбэк и возврат, пришедшие одновременно, обрабатываются по очереди, поэтому заказ никогда не создаётся дважды. Затем покупатель видит стандартную страницу подтверждения заказа. Если заказ был поставлен на удержание, страница показывает Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

Если Hubtel ещё не подтвердил платёж, когда покупатель возвращается, появляется страница Payment confirmation с сообщением We are waiting for Hubtel to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. и кнопками Check again и Back to checkout. Заказ создаётся, как только Hubtel подтверждает платёж. Если Hubtel уже сообщил, что эта попытка оплаты не удалась, покупатель возвращается к оформлению заказа с сообщением The Hubtel payment was not completed. You can try again or choose another payment method. Корзина сохраняется.

Если покупатель нажимает Cancel на странице Hubtel, модуль сначала проверяет, не был ли платёж всё-таки произведён. Если нет, покупатель возвращается к оформлению заказа с сообщением The Hubtel payment was cancelled. You can try again or choose another payment method. Корзина сохраняется. Последующий платёж по отменённой странице Hubtel всё равно принимается.

Если Hubtel не может начать платёж, покупатель остаётся на этапе оформления заказа с коротким сообщением, например Could not connect to Hubtel. Please try again in a moment., Hubtel could not start the payment. Please try again or choose another payment method. или, при неверных учётных данных, Hubtel payments are not available at the moment. Please choose another payment method. Подробности записываются в журнал.

Модуль не поддерживает возвраты из PrestaShop, подписки, сохранённые карты и выбор платёжного канала внутри магазина.

Заказы

Статусы заказов

No order yet: покупатель отправлен в Hubtel и не оплатил, либо Hubtel ещё не подтвердил платёж. Существует только корзина.

Payment accepted: платёж подтверждён на точную сумму корзины в GHS. Платёж записывается с ID транзакции Hubtel, а примечание показывает сумму, транзакцию Hubtel, способ оплаты и референс.

Hubtel payment on hold: Hubtel сообщил о сумме оплаты, отличающейся от суммы корзины, либо корзина не в GHS. Заказ не был отмечен как оплаченный; сумма, которую Hubtel фактически списал, записывается как платёж, а примечание объясняет расхождение. Проверьте платёж в панели Hubtel и выполните заказ или сделайте возврат вручную. Если другая попытка оплаты той же корзины позже будет оплачена на правильную сумму, заказ перейдёт в статус Payment accepted.

Если другая попытка по уже оплаченному заказу тоже оплачена, заказ не меняется. Примечание просит вас вернуть дубликат через панель Hubtel. Платёж по отменённому или возвращённому заказу добавляет примечание, а заказ никогда не открывается заново автоматически. Когда Hubtel сообщает, что платёж возвращён, к заказу добавляется примечание.

Блок оплаты Hubtel

На странице заказа показан блок Hubtel payment со всеми попытками оплаты корзины заказа: дата, референс, страница оплаты Hubtel, сумма, статус Hubtel, транзакция и результат. Под попытками перечислены Hubtel notes заказа, сначала самые новые.

Кнопка Check Hubtel payment status проверяет последние попытки заказа (до 5, сначала самые новые; проверка останавливается, как только заказ оплачен), применяет результат и добавляет примечание со статусом каждой попытки. Результат отображается в блоке. Нужно право на редактирование заказов; доступ к страницам модулей не требуется. Кнопка доступна, когда заказ уже существует. Оплаченная корзина без заказа подтверждается колбэком, возвратом покупателя или cron.

Возвраты

Возвраты из PrestaShop не поддерживаются. Верните платёж в панели Hubtel, а затем зарегистрируйте возврат в PrestaShop. Стандартные кнопки возврата PrestaShop на странице заказа не отправляют деньги обратно через Hubtel.

Лицензионный ключ

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Hubtel Pay Gateway — это первый блок на странице Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой лицензия действительна, и ваш домен) и кнопки Check now, чтобы проверить статус ещё раз, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: presta-payment-hubtel и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока соответствуют языку back office (включены английский и русский).

Если ключ не принят, блок сообщает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on и дату. После смены адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: домене основного магазина, в том числе при мультимагазинной настройке. Удаление ключа из магазина не освобождает слот его домена. Освободите слот в своём аккаунте vibefox.net.

Без активного ключа Hubtel не отображается покупателям на этапе оформления заказа. Если оплата всё же начата, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в back office, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его на этапе оформления заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи продолжают подтверждаться также фоновыми проверками платежей.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова, пока вы работаете в back office: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Для проверки лицензии cron-задача не нужна. При удалении или сбросе модуля лицензионный ключ и статус лицензии всегда удаляются.

Устранение неполадок

Hubtel не появляется на этапе оформления заказа: проверьте, что лицензия активна, Enable/Disable включено, API ID, API Key и номер торгового счёта заполнены, а валюта корзины — GHS. В разделе Payment > Preferences проверьте, что модуль разрешён для GHS, страны покупателя и группы покупателя. На странице настроек появляется предупреждение, если учётные данные или валюта указаны неверно.

Платёж прошёл, но заказ не создан: платёж не удалось подтвердить. Включите Debug log и посмотрите поле Log на странице модуля. HTTP 401 или 403 при проверке статуса означает, что API-ключи неверны или IP сервера не внесён Hubtel в белый список. Также проверьте, что URL колбэка доступен из интернета и что cron-URL вызывается. Как только Hubtel ответит, заказ создаст следующий колбэк, фоновая проверка или возврат покупателя.

Колбэк отвечает Unknown reference: референс платежа не принадлежит ни одному платежу этого магазина.

Колбэк отвечает Payment status unavailable: Transaction Status API недоступен или отклонил запрос, либо корзину в этот момент подтверждал другой запрос. Платёж будет повторно проверен в фоновом режиме через 5 минут.

Колбэк отвечает Gateway not configured: не заполнены API ID, API Key или номер торгового счёта. Заполните их; платёж будет повторно проверен в фоновом режиме.

Колбэк отвечает Invalid request или Invalid ClientReference: запрос не содержал корректного колбэка Hubtel.

URL колбэка в браузере показывает Method not allowed: это нормально. URL принимает только запросы от Hubtel.

URL cron отвечает Forbidden: токен в URL неверный. Скопируйте cron-URL точно так, как он показан в настройках.

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

Покупатель видит ошибку при выборе Hubtel: включите Debug log и посмотрите журнал. Неверные API-ключи дают Hubtel payments are not available at the moment. Проблема со связью даёт Could not connect to Hubtel. Корзина в другой валюте даёт Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method.

Для разработчиков: хук actionWcpHubtelPayIcon меняет значок способа оплаты, а actionWcpHubtelPayPaymentDescription меняет описание платежа на странице Hubtel (до 100 символов).

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Hubtel Pay Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete data on uninstall включено, настройки и журнал этого модуля удаляются. Если выключено, все настройки сохраняются для последующей переустановки. Данные Hubtel, сохранённые для заказов, и статус заказа Hubtel payment on hold всегда остаются. Существующие заказы сохраняют свои примечания об оплате и ID транзакций.

Hubtel — торговая марка её владельца. Этот модуль не аффилирован с Hubtel и не одобрен Hubtel.