VibeFox Hubtel for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

PHP: 8.0 или новее с расширением cURL.

Валюта: только ганские седи (GHS). Способ оплаты скрыт на оформлении заказа, если валюта заказа не 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 минут (см. Configuration).

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

Установка

Загрузка — это один zip-файл с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_hubtel_pay-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_hubtel_pay.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаковый для обеих версий.

OpenCart 3

1. В админ-панели перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_hubtel_pay-oc3-(version).ocmod.zip. У расширения нет модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload из этого пакета в корневую папку вашего магазина.

2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Hubtel Pay Gateway и нажмите Install (зелёная кнопка +). Вашему пользователю админки нужно право изменять список платёжных расширений.

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

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

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

6. Добавьте cron URL из раздела Payment confirmation в cron вашего сервера.

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

OpenCart 4

1. В админ-панели перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_hubtel_pay.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на этой же странице. Нажмите Install (зелёная кнопка +) рядом с ним.

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Hubtel Pay Gateway, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ, учётные данные Hubtel и cron так же, как в шагах 3–7 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличаются только callback URL и cron URL (см. Payment confirmation).

Новая установка начинается с выключенным способом оплаты.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Hubtel Pay Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если не заполнены API ID, API Key или номер торгового счёта, а также если валюта магазина по умолчанию не GHS. В обоих случаях Hubtel скрыт на оформлении заказа. Также страница предупреждает, если у валюты GHS больше 2 знаков после запятой (задайте это в System > Localisation > Currencies). Без права изменять расширение страница показывает настройки, но не может их сохранить.

При сохранении Title не должно быть пустым и не должно превышать 128 символов (Enter a title for the payment method (1 to 128 characters).), Sort Order должно быть целым числом, Total — числом не меньше 0, а географическая зона и статусы заказов должны существовать; иначе ничего не сохраняется. Если способ оплаты включён без учётных данных, настройки сохраняются с предупреждением.

Hubtel

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

Title: название способа оплаты, которое видит покупатель на оформлении заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: Mobile Money or card (Hubtel). Обязательное поле.

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения, рядом со значками Mobile Money и карт. По умолчанию: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.

Sort Order: позиция Hubtel среди способов оплаты на оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать Hubtel только для платёжных адресов из выбранной географической зоны. По умолчанию: All zones. Географические зоны настраиваются в System > Localisation > Geo Zones.

Total: сумма оформления заказа в валюте магазина по умолчанию, которую заказ должен достичь, прежде чем будет предложен Hubtel. Оставьте поле пустым, чтобы не задавать минимум.

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

Скопируйте 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. Введите новое значение, только если хотите его изменить. Чтобы удалить сохранённый ключ, отметьте Clear saved API Key под полем и нажмите Save.

Номер торгового счёта (POS Sales ID): платежи поступают на этот счёт Hubtel и проверяются по нему.

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

Callback URL: callback сообщает вашему магазину, что платёж выполнен. Этот URL передаётся в Hubtel с каждым платежом, поэтому в панели Hubtel ничего настраивать не нужно. В OpenCart 3 он выглядит как https://your-store/index.php?route=extension/payment/wcp_hubtel_pay/callback, в OpenCart 4 — как https://your-store/index.php?route=extension/wcp_hubtel_pay/payment/wcp_hubtel_pay.callback. Он формируется из адреса витрины вашей установки OpenCart. Он должен быть доступен из интернета: не должно быть парольной защиты или брандмауэра, блокирующего Hubtel. Callback работает и тогда, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы платёжных расширений, а в OpenCart 4 расширение добавляет стартовое действие (startup action), которое пропускает callback, cron URL и возврат покупателя из Hubtel.

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

Фоновые проверки платежей (cron): cron URL с секретным токеном, который создаётся при установке расширения. Вызывайте его каждые 5 минут из cron вашего сервера, например с помощью curl. Платежи без подтверждения затем автоматически перепроверяются в Hubtel: через 20 минут после отправки покупателя в Hubtel, ещё раз через час, если платёж всё ещё не оплачен, и до 5 раз с возрастающими интервалами, если Hubtel был недоступен. В OpenCart 4 cron URL имеет маршрут extension/wcp_hubtel_pay/payment/wcp_hubtel_pay.cron вместо extension/payment/wcp_hubtel_pay/cron; копируйте его точно так, как он показан в настройках. Храните URL в секрете. URL отвечает короткой строкой, например OK checked=0.

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Заказ получает статус только после того, как Hubtel подтвердит платёж. Каждое поле ниже перечисляет статусы заказов вашего OpenCart.

Order status after payment: статус, который ставится после того, как Hubtel подтвердил платёж на точную сумму заказа в GHS. По умолчанию: В обработке.

Hubtel payment on hold status: статус, который ставится, когда Hubtel сообщает об оплаченной сумме, отличающейся от суммы заказа, или когда заказ не в GHS. Примечание в истории заказа объясняет причину. По умолчанию: Ожидание, потому что в OpenCart нет статуса On hold. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

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

Debug log: записывает вызовы API и callbacks в файл hubtel_p_debug.log.php в папке журналов OpenCart (storage/logs). Файл нельзя открыть из браузера; при достижении 5 МБ он переносится в hubtel_p_debug.old.log.php. Ключи и данные покупателей не записываются. Ошибки и предупреждения записываются всегда, даже когда опция выключена. По умолчанию: выключено.

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

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

Импорт / экспорт

Export: Download JSON сохраняет настройки в файл JSON. API Key не экспортируется.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённый API Key остаётся.

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

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

В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после того, как Hubtel подтвердит платёж через Transaction Status API: по callback, при проверке в момент возврата покупателя, при фоновой проверке или по кнопке на странице заказа. Callback и возврат покупателя, пришедшие одновременно, обрабатываются по очереди, поэтому платёж никогда не применяется дважды. Затем заказ получает статус стандартным способом OpenCart, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Если заказ был переведён в статус удержания, страница показывает 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 всё равно принимается.

В OpenCart 4 сообщения об отменённом или неудачном платеже показываются над страницей оформления заказа. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; OpenCart 4 обновляет заказ в процессе оформления, поэтому после отмены или неудачного платежа покупатель оплачивает тот же заказ новой попыткой оплаты. Перед новой попыткой расширение запрашивает у Hubtel неподтверждённые попытки этого заказа и более ранних заказов той же корзины (за последние 24 часа). Если одна из них оказывается оплаченной, эта оплата применяется, и покупатель переходит на страницу успеха, а не платит дважды. Изменение корзины, включая новое количество, считается новой корзиной, которой нужна собственная оплата.

OpenCart 4 сохраняет заказ в оформлении до показа страницы успеха. Если этот заказ был закрыт без оплаты (например, вы его отменили), покупатель возвращается на оформление заказа с сообщением The Hubtel payment was not completed. You can try again or choose another payment method., а следующее нажатие Confirm Order оплачивает новый заказ. Если заказ уже оплачен, а в корзине теперь новая покупка, Confirm Order перезагружает страницу оформления, а следующее нажатие Confirm Order оплачивает новый заказ. Оплаченный заказ никогда не отображается как оплаченный для другой корзины.

Если Hubtel не может начать платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, например 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. Подробности записываются в журнал.

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

Заказы

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

Без статуса (отсутствующий заказ): покупатель был отправлен в Hubtel и не оплатил, либо Hubtel ещё не подтвердил платёж. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным на Missing Orders.

Order status after payment (по умолчанию Processing): платёж подтверждён на точную сумму заказа в GHS. Примечание показывает сумму, транзакцию Hubtel, способ оплаты и справочный номер.

Hubtel payment on hold status (по умолчанию Pending): Hubtel сообщил об оплаченной сумме, которая отличается от суммы заказа, или заказ не в GHS. Заказ не был отмечен как оплаченный, а примечание объясняет расхождение. Проверьте платёж в панели Hubtel и выполните заказ или вручную верните деньги. Если позже оплатят другую попытку этого же заказа на правильную сумму, заказ перейдёт в статус Order status after payment.

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

Примечания — это записи в History заказа, которые покупатель не видит.

Вкладка VibeFox Hubtel Pay Gateway

В Sales > Orders откройте заказ, оплаченный через Hubtel. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Hubtel Pay Gateway показывает Hubtel payment attempts заказа: дату, справочный номер и платёжную сессию Hubtel, сумму, статус Hubtel, транзакцию и результат. Под попытками перечислены Hubtel notes заказа, сначала новые. Вкладка показывается пользователям, у которых есть доступ к расширению.

Кнопка Check Hubtel payment status проверяет последние попытки заказа (до 5, сначала новые, останавливаясь, как только заказ оплачен), применяет результат и добавляет примечание со статусом каждой попытки. Результат показывается на вкладке. Нужно право изменять заказы (Sales > Orders, настраивается в System > Users > User Groups). Кнопка работает и для заказа без статуса. Статус, установленный этой кнопкой, записывается напрямую, без писем о заказе и обновления остатков; callback, возврат покупателя и cron устанавливают его стандартным способом.

Возвраты

Возвраты из OpenCart не поддерживаются. Верните платёж в панели Hubtel, затем зафиксируйте возврат в OpenCart. Возвраты товаров в Sales > Returns не возвращают деньги через Hubtel.

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

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

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

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

Без действующего ключа Hubtel не показывается покупателям на оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Администратор, вошедший в админку в том же браузере, всё ещё видит способ оплаты в магазине, отмеченный (unlicensed — visible to admins only), чтобы вы могли настроить и проверить расширение до покупки ключа. В OpenCart 4 этот предпросмотр недоступен: магазин не видит вход администратора, поэтому без действующего ключа способ оплаты скрыт от всех. После того как вы один раз откроете страницу Edit, на Dashboard админки появится напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: платежи, уже начатые, по-прежнему подтверждаются, в том числе фоновыми проверками.

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

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

Hubtel не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, заполнены API ID, API Key и номер торгового счёта, а валюта заказа — GHS. Также проверьте, что платёжный адрес входит в выбранную Geo Zone, а сумма заказа достигает Total, заданного в настройках. Страница настроек показывает предупреждение, если учётные данные или валюта неверны.

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

Callback отвечает Unknown reference: справочный номер платежа не принадлежит платежу этого магазина.

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

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

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

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

Cron URL отвечает Forbidden: токен в URL неверный. Скопируйте cron URL точно так, как он показан в настройках. После повторной установки с включённым Delete data on uninstall токен новый.

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

Покупатель видит ошибку после Confirm Order: включите 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. Сообщение This payment method is not available. Please reload the checkout page. означает, что оформление заказа больше не соответствует заказу, или способ оплаты тем временем выключили.

Для разработчиков: событие OpenCart wcp_hubtel_pay_icon меняет значок способа оплаты, а wcp_hubtel_pay_payment_description меняет описание оплаты на странице Hubtel.

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Hubtel Pay Gateway. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Orders, которые при повторной установке вернутся к значениям по умолчанию. Событие OpenCart этого расширения также удаляется (в OpenCart 4 — также его события и стартовое действие, которое пропускает callback, cron URL и возврат покупателя в режиме обслуживания). Если Delete data on uninstall включено, удаляются остальные настройки (название, описание, учётные данные API, cron-токен, переключатель журнала отладки) и журнал. Если выключено, они сохраняются для повторной установки. Попытки оплаты Hubtel по заказам всегда сохраняются, поэтому запоздалые callbacks и проверки продолжают работать после повторной установки. Существующие заказы сохраняют примечания об оплате.

В OpenCart 4, чтобы удалить и файлы расширения, перейдите в Extensions > Installer после удаления и нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Hubtel Pay Gateway в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

Hubtel является товарным знаком его правообладателя. Это расширение не аффилировано с Hubtel и не одобрено им.