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. Залиште поле порожнім, якщо мінімальної суми не потрібно.

Облікові дані 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. Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережений ключ, позначте 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 — її події та стартова дія (startup action), яка пропускає callback, cron URL і повернення покупця в режимі обслуговування). Якщо Delete data on uninstall увімкнено, видаляються інші налаштування (назва, опис, облікові дані API, cron-токен, перемикач журналу налагодження) та журнал. Якщо вимкнено, вони зберігаються для повторного встановлення. Спроби оплати Hubtel за замовленнями завжди зберігаються, тож запізнілі callbacks і перевірки продовжують працювати після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату.

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

Hubtel є торговельною маркою її власника. Це розширення не пов'язане з Hubtel і не схвалене ним.