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 під назвою плагіна на сторінці плагінів.

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 приймаються платежі та за ним же звіряються.

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

Зворотний виклик (callback) повідомляє ваш магазин про успішне здійснення платежу. 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. Деталі записуються до журналу.

Спосіб оплати працює під час класичного оформлення замовлення, у блоці Checkout і на сторінці 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 і не схвалений нею.