VibeFox Hubtel for WooCommerce — Помощь

Требования

WordPress: 6.2 или новее.

WooCommerce: 8.0 или новее, установлен и активен. Без него плагин отказывается активироваться.

PHP: 8.0 или новее.

Валюта: только ганский седи (GHS). Для других валют способ оплаты скрывается при оформлении заказа. Оставьте количество десятичных знаков в WooCommerce равным 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 нет публичной песочницы. Все платежи реальные.

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

Установка

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

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > Hubtel > Manage или нажмите Settings под названием плагина на странице Plugins.

4. Введите ваш лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

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

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

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

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Hubtel. Над полями страница предупреждает, если API ID, API Key или номер счёта продавца не заполнены, а также если валюта магазина отличается от GHS. В обоих случаях способ Hubtel скрывается при оформлении заказа. Страница также предупреждает, если в магазине используется более 2 десятичных знаков. В списке способов оплаты шлюз помечается как требующий настройки, пока не введены учётные данные.

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

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

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. You will be redirected to Hubtel to complete the payment.

Учётные данные 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. Храните его в секрете.

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

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

Колбэк сообщает вашему магазину о совершении платежа. URL колбэка, показанный в этом разделе, отправляется в Hubtel с каждым платежом, поэтому в панели Hubtel ничего настраивать не нужно. Он имеет вид https://your-site/wc-api/hubtel_pay/. Он должен быть доступен из интернета: без режима обслуживания, защиты паролем или блокировки Hubtel брандмауэром.

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

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

Debug log: Log API calls and callbacks в WooCommerce > Status > Logs, источник wcp_hubtel_pay, без ключей и данных покупателей. Ошибки записываются всегда. По умолчанию: выключено.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Hubtel data saved on orders is kept). По умолчанию: выключено.

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

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

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

Если покупатель нажимает Cancel на странице Hubtel, плагин сначала проверяет, не был ли платёж всё же совершён. Если нет, покупатель возвращается на страницу Pay for order с сообщением: The Hubtel payment was cancelled. You can try again or choose another payment method.

Если 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. Подробности записываются в журнал.

Способ оплаты работает при классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Он совместим с высокопроизводительным хранилищем заказов WooCommerce (HPOS).

В плагине нет возвратов из WooCommerce, нет подписок, нет сохранённых карт и нет выбора платёжного канала внутри WooCommerce.

Заказы

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

Pending payment: покупатель был перенаправлен в Hubtel и ещё не совершил оплату, либо Hubtel ещё не подтвердил платёж.

Processing: платёж подтверждён. Заказы, содержащие только виртуальные загружаемые товары, переходят в статус «Выполнен» — так WooCommerce работает по умолчанию. В примечании к заказу указываются сумма, транзакция Hubtel, способ оплаты и идентификатор платежа. ID транзакции соответствует ID транзакции Hubtel.

On hold: Hubtel сообщил об оплаченной сумме, которая отличается от суммы заказа, либо заказ оформлен не в GHS (примечание Hubtel amount/currency mismatch); либо поступил платёж по заказу, который был отменён. Заказ не отмечается как оплаченный. Проверьте платёж в панели Hubtel и завершите заказ или оформите возврат вручную.

Failed: Hubtel сообщил, что последняя попытка оплаты незавершённого заказа завершилась неудачей, и Transaction Status API подтверждает, что заказ не оплачен. Покупатель может повторить попытку из заказа. Неудача, о которой сообщил только колбэк, никогда не переводит заказ в статус «Не удался».

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

Проверки оплаты

Примерно через 20 минут после того, как покупатель был перенаправлен в Hubtel, фоновая проверка (WooCommerce Action Scheduler) запрашивает статус платежа у Hubtel на случай, если колбэк был утерян, а покупатель не вернулся в магазин. Неоплаченная попытка проверяется ещё раз через час. Если API Hubtel недоступен, проверка повторяется до 5 раз с увеличивающимися интервалами.

Действие с заказом Check Hubtel payment status проверяет последние попытки оплаты по заказу (до 5, начиная с самой новой), применяет результат и добавляет примечание со статусом каждой попытки.

Возвраты

Возвраты из WooCommerce не поддерживаются. Выполните возврат в панели Hubtel, а затем оформите ручной возврат в WooCommerce.

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

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

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

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

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

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

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

Оплата прошла, но заказ остаётся в статусе «В ожидании оплаты»: платёж не удалось подтвердить. Откройте WooCommerce > Status > Logs, источник wcp_hubtel_pay. Код HTTP 401 или 403 при проверке статуса означает, что API-ключи неверны либо IP-адрес сервера не внесён в белый список Hubtel. Также убедитесь, что URL колбэка доступен из интернета. После исправления откройте заказ и выполните Order actions > Check Hubtel payment status. Фоновые проверки также подтвердят заказ, как только Hubtel ответит.

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

Колбэк возвращает Payment status unavailable: не удалось связаться с Transaction Status API или запрос был отклонён. Платёж будет перепроверен в фоновом режиме.

Заказ находится в статусе «На удержании» с примечанием о несовпадении суммы или валюты: Hubtel сообщил об оплаченной сумме, которая отличается от суммы заказа, либо заказ оформлен не в GHS. Проверьте платёж в панели Hubtel и завершите заказ или оформите возврат вручную.

Покупатель видит ошибку при оформлении заказа: включите Debug log и посмотрите журнал. Неверные ключи API вызывают сообщение Hubtel payments are not available at the moment. Проблема с подключением приводит к Could not connect to Hubtel.

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

Для разработчиков: фильтр hubtel_p_icon меняет значок способа оплаты, а hubtel_p_payment_description меняет описание платежа на странице Hubtel (до 100 символов).

Удаление

При деактивации плагина все данные сохраняются; отменяются только незавершённые фоновые проверки платежей. Чтобы удалить плагин, деактивируйте и удалите его на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза, собственные параметры плагина, незавершённые фоновые проверки и журналы удаляются, только если была включена опция Delete data on uninstall. В противном случае они сохраняются для повторной установки. Данные Hubtel, сохранённые в заказах, представляют собой историю платежей и сохраняются всегда. Существующие заказы сохраняют свои примечания об оплате и ID транзакций.

Hubtel — товарный знак соответствующего владельца. Этот плагин не связан с Hubtel и не одобрен им.