VibeFox Hubtel for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта: лише ганський седі (GHS). Спосіб оплати приховується на етапі оформлення замовлення для інших валют. Залиште 2 десяткові знаки для валюти GHS, оскільки 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 нічого не потрібно налаштовувати. З дружніми URL він має такий вигляд: 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 для модуля. Тексти блоку відповідають мові бек-офісу (включено англійську та російську).

Якщо ключ не прийнято, блок повідомляє причину, наприклад 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 не знає, що ви увійшли до бек-офісу, тому спосіб оплати приховано і для вас: модуль можна налаштувати до купівлі ключа, але протестувати його на етапі оформлення замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: платежі, що вже розпочаті, також підтверджуються фоновими перевірками платежів.

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

Callback відповідає Unknown reference: референс платежу не належить жодному платежу цього магазину.

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

Callback відповідає Gateway not configured: не заповнено API ID, API Key або номер торгового рахунку. Заповніть їх; платіж буде повторно перевірено у фоновому режимі.

Callback відповідає Invalid request або Invalid ClientReference: запит не містив коректного зворотного виклику Hubtel.

URL зворотного виклику в браузері показує Method not allowed: це нормально. URL приймає лише запити від Hubtel.

Cron-URL відповідає 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.