VibeFox Paymob for OpenCart — Допомога

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 та новіші (перевірено на 4.1.0.3).

PHP: 8.0 або новіша.

Обліковий запис Paymob: обліковий запис мерчанта в одній із підтримуваних країн: Єгипет, Об'єднані Арабські Емірати, Саудівська Аравія, Оман або Пакистан. Потрібні чотири значення з панелі Paymob: API-ключ, ID інтеграції онлайн-платежів, ID iFrame сторінки оплати та секрет HMAC.

Валюта: валюта оформлення має бути валютою вашої країни Paymob: EGP для Єгипту, AED для ОАЕ, SAR для Саудівської Аравії, OMR для Омана, PKR для Пакистану. Додайте її в System > Localisation > Currencies, якщо її ще немає у вашому магазині. За іншої валюти спосіб оплати приховується на оформленні замовлення. Мультивалютні облікові записи Paymob не підтримуються.

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

Встановлення

Файл — це один ZIP-архів з пакетами для обох версій OpenCart. Розпакуйте його на своєму комп'ютері. Він містить README.txt, пакет для OpenCart 3 wcp_paymob_pay-oc3-(version).ocmod.zip і пакет для OpenCart 4 wcp_paymob_pay.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

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

2. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox Paymob Pay і натисніть Install (зелена кнопка +).

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

4. Виберіть Paymob country і введіть API-ключ, ID інтеграції, ID iFrame та секрет HMAC (див. Налаштування).

5. На панелі Paymob задайте callback-URL вашої інтеграції як адресу, показану в розділі Callbacks (див. Callbacks).

6. Увімкніть Enable/Disable і натисніть Save. Перевірте платіж з ID тестової інтеграції Paymob, а потім введіть ID вашої робочої інтеграції.

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_paymob_pay.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з назви файлу, і перейменований пакет не працює.

2. Пакет з'являється у списку встановлених розширень на тій самій сторінці. Натисніть біля нього Install (зелена кнопка +).

3. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox Paymob Pay, натисніть Install (зелена кнопка +), потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ, ключі та ID Paymob і callback-URL так само, як у кроках 3–6 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях. Відрізняється лише callback-URL (див. Callbacks).

Нове встановлення починається з вимкненим способом оплати.

Налаштування

Усі налаштування містяться на сторінці розширення: Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка попереджає, якщо бракує одного з чотирьох значень Paymob (доти Paymob приховано на оформленні замовлення), і якщо валюту магазину за замовчуванням не приймає вибрана країна Paymob.

Під час збереження Title не може бути довшим за 128 символів, Sort Order має бути цілим числом (від'ємні числа дозволені), Total — числом не менше 0, а вибрані геозона та статуси замовлень мають існувати; інакше нічого не зберігається, і сторінка називає поле.

Paymob

Enable/Disable: Enable Paymob вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

Title: назва способу оплати, яку бачать покупці на оформленні замовлення. Вона також зберігається в замовленні як назва способу оплати, до 128 символів. Якщо поле порожнє, покупці бачать Paymob. За замовчуванням: Paymob.

Description: текст, який показується покупцю на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Pay securely by card or mobile wallet on the Paymob payment page. Залиште порожнім, щоб текст не показувався.

Sort Order: позиція Paymob серед способів оплати на оформленні замовлення. Залиште порожнім або введіть ціле число.

Geo Zone: пропонувати Paymob лише для платіжних адрес у вибраній геозоні. За замовчуванням: All zones. Геозони налаштовуються в System > Localisation > Geo Zones. На OpenCart 4, якщо магазин не запитує платіжну адресу, використовується адреса доставки.

Total: сума оформлення замовлення у валюті магазину за замовчуванням, яку замовлення має досягти, щоб пропонувався Paymob. Залиште порожнім, щоб пропонувати Paymob за будь-якої суми.

Обліковий запис Paymob

Усі значення знаходяться на панелі мерчанта Paymob. Окремого тестового режиму немає: для тестових платежів введіть ID інтеграції, що працює в тестовому режимі. Жодні інші налаштування не змінюються.

Paymob country: країна вашого облікового запису Paymob. Вона визначає сервер API та сторінки оплати, а валюта оформлення має бути валютою цієї країни. За замовчуванням: Egypt.

API key: на панелі Paymob у розділі Settings > Account info > API Key.

Integration ID: на панелі Paymob у розділі Developers > Payment Integrations: числовий ID інтеграції онлайн-оплати карткою або гаманцем. Способи оплати, що пропонуються на сторінці Paymob, — це способи цієї інтеграції.

iFrame ID: на панелі Paymob у розділі Developers > iframes: числовий ID платіжного iFrame.

HMAC secret: на панелі Paymob у розділі Settings > Account info > HMAC. Обов'язкове поле: замовлення позначаються оплаченими лише callback, підписаними цим секретом.

Integration ID і iFrame ID можуть містити лише цифри. Пробіли видаляються. Будь-яке інше значення відхиляється під час збереження з повідомленням, що поле має must contain digits only — the previous value was kept. Інші поля зберігаються.

Збережені API-ключ і секрет HMAC ніколи не показуються повторно. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережене значення, позначте під полем Clear the saved API key on save або Clear the saved HMAC secret on save і натисніть Save.

Callbacks

Paymob повідомляє вашому магазину про кожну транзакцію. На панелі Paymob відкрийте Developers > Payment Integrations, оберіть свою інтеграцію, натисніть Edit і встановіть як Transaction processed callback, так і Transaction response callback на Callback URL, показаний у цьому розділі. В OpenCart 3 він має такий вигляд: https://your-store/index.php?route=extension/payment/wcp_paymob_pay/callback, в OpenCart 4 — такий: https://your-store/index.php?route=extension/wcp_paymob_pay/payment/wcp_paymob_pay.callback. Він формується з адреси вітрини вашої інсталяції OpenCart. Скопіюйте його кнопкою Copy. Розділ також містить посилання на панель Paymob вибраної країни. Задайте URL в кожній інтеграції, яку використовуєте, зокрема в тестовій.

Transaction processed callback надсилає сервер Paymob. Transaction response callback повертає покупця до вашого магазину. Обидва підписані вашим секретом HMAC і перевіряються розширенням. Callback без дійсного підпису відхиляються і нічого не змінюють. Якщо серверний callback запізнюється або губиться, підписане повернення покупця теж підтверджує платіж. URL callback працює й тоді, коли магазин перебуває в режимі обслуговування: OpenCart 3 пропускає запити платіжних розширень, а в OpenCart 4 розширення додає startup-дію, яка пропускає callback і повернення покупця.

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Статус воно отримує лише після того, як Paymob повідомить про коректно підписану транзакцію. Відхилений платіж залишає замовлення без статусу; покупець повертається до оформлення з кошиком, що зберігся. Кожне поле нижче перелічує ваші статуси замовлень OpenCart.

Order Status After Payment: транзакцію Paymob сплачено з очікуваними сумою та валютою. За замовчуванням: В обробці.

Awaiting Paymob Payment Status: транзакція очікує, наприклад готівковий платіж або платіж через кіоск. Замовлення отримує статус після оплати, коли Paymob його підтвердить. За замовчуванням: Очікування.

Paymob Payment On Hold Status: Paymob лише авторизував суму (спишіть її на панелі Paymob), сплачена сума або валюта не збігаються із замовленням, або платіж надійшов для скасованого замовлення. Примітка пояснює причину. За замовчуванням: Очікування, оскільки в OpenCart немає статусу On hold. Власний статус можна створити в System > Localisation > Order Statuses і вибрати його тут.

Наступні три поля повідомляють розширенню, які статуси використовує ваш магазин. Розширення їх ніколи не встановлює.

Payment Error Status: статус, який ваш магазин використовує для замовлень із помилкою оплати. Транзакція в очікуванні може перевести таке замовлення в статус очікування. За замовчуванням: Невдало.

Cancelled Order Status: статус, який ваш магазин використовує для скасованих замовлень. Платіж, отриманий для такого замовлення, переводить його на утримання або лише додає примітку, якщо його вже було сплачено раніше. За замовчуванням: Скасовано.

Refunded Order Status: статус, який ваш магазин використовує для замовлень із поверненням коштів. Платіж, отриманий для такого замовлення, лише додає примітку. За замовчуванням: Повернено.

Додатково

Debug log: записує кроки оплати та callback у paymob_p_debug.log.php у папці журналів OpenCart (storage/logs). Файл не можна відкрити через веб. Помилки та відхилені callback записуються завжди, навіть коли опцію вимкнено. Ключі, токени та дані покупців ніколи не записуються. За замовчуванням: вимкнено.

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

Clean uninstall: якщо увімкнено, під час видалення розширення видаляються налаштування шлюзу та журнал. ID Paymob, збережені для замовлень (спроби оплати), завжди зберігаються. За замовчуванням: вимкнено.

Імпорт / Експорт

Export: Download JSON зберігає налаштування у файл JSON. API-ключ і секрет HMAC не експортуються.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування. Збережені секрети залишаються.

Оформлення замовлення

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Paymob). На кроці Confirm Order покупець бачить ваш опис і примітку You will be redirected to the secure Paymob payment page to pay by card or mobile wallet. OpenCart створює замовлення на цьому кроці, все ще без статусу. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення. Коли покупець натискає Confirm Order, розширення реєструє нове замовлення Paymob на суму замовлення у валюті замовлення, передає в Paymob ім'я, e-mail, телефон і платіжну адресу покупця (на OpenCart 4, якщо магазин не запитує платіжну адресу, — адресу доставки) та надсилає покупця на сторінку оплати Paymob вашої країни. Там покупець платить одним зі способів вашої інтеграції, наприклад карткою або мобільним гаманцем.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після того, як Paymob підтвердить його підписаною транзакцією. Далі замовлення отримує статус звичайним для OpenCart способом, зі звичайними листами про замовлення та оновленням залишків, і покупець бачить сторінку успішного оформлення OpenCart. Платіж в очікуванні (наприклад, готівка або кіоск) чи авторизований платіж також надають замовленню статус — очікування або «на утриманні» — і ведуть на сторінку успіху.

Якщо замовлення ще підтверджується, коли покупець повертається, сторінка Payment confirmation показує Paymob accepted your payment and we are confirming it. You will receive an e-mail as soon as your order is confirmed — there is no need to pay again. Для платежу в очікуванні текст такий: Your Paymob payment is pending (for example a cash or kiosk payment). Complete it as Paymob instructed you: your order is confirmed as soon as Paymob reports the payment. На сторінці є кнопка Check again і кнопка Back to checkout.

Якщо платіж відхилено, покупець повертається до оформлення з тим самим кошиком і повідомленням Your Paymob payment was not completed. Please try again or choose another payment method. Кожна нова спроба реєструє власне замовлення Paymob, тож покупець може оплатити кошик знову. OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order; OpenCart 4 зберігає одне замовлення для оформлення і оновлює його, тож покупець оплачує те саме замовлення новою спробою. Якщо відповідь від Paymob не вдалося перевірити, покупець бачить We could not verify the response from Paymob. If you were charged, your order will be updated as soon as Paymob confirms the payment. Якщо інше замовлення з того самого кошика вже оплачено або очікує оплати (наприклад, у другій вкладці браузера), покупець переходить на сторінку успіху замість повторної оплати. На OpenCart 4 повідомлення після повернення з Paymob показуються над сторінкою оформлення.

OpenCart 4 зберігає замовлення в оформленні, доки не буде показано сторінку успіху. Якщо це замовлення тим часом закрито без оплати (наприклад, ви його скасували), покупець повертається до оформлення з повідомленням Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., і наступне Confirm Order оплачує нове замовлення. Якщо це замовлення вже має статус, а в кошику тепер інші товари або кількості, покупець також повертається до оформлення, і новий кошик отримує нове замовлення.

Якщо Paymob не може розпочати платіж, покупець залишається на кроці Confirm Order з коротким повідомленням над кнопкою, наприклад Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. або Could not connect to Paymob. Please try again in a moment. Технічна причина записується в журнал.

Розширення приймає лише разові платежі на сторінці Paymob. Воно не підтримує збережені картки, підписки, форму картки, вбудовану у ваш сайт, і повернення коштів з адмін-панелі.

Замовлення

Статуси замовлень

No status (missing order): покупця надіслано до Paymob, і він не сплатив, платіж відхилено, або Paymob ще не підтвердив платіж. У розділі Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders.

На OpenCart 4 неоплачене замовлення оформлення може отримати статус Voided, який OpenCart 4 встановлює, коли покупець повертається до кроку Confirm Order. Розширення вважає таке замовлення замовленням без статусу, і подальший платіж його все одно підтверджує.

Order Status After Payment (default Processing): Paymob підтвердив платіж. Примітка показує транзакцію, суму та тип картки з останніми чотирма цифрами.

Awaiting Paymob Payment Status (default Pending): платіж очікує в Paymob, наприклад готівка або платіж через кіоск. Замовлення переходить до статусу після оплати, коли Paymob підтверджує платіж.

Paymob Payment On Hold Status (default Pending): Paymob лише авторизував суму і не списав її (спишіть її на панелі Paymob; замовлення переходить до статусу після оплати, коли надійде callback списання); або сплачена сума чи валюта не збігаються із замовленням; або платіж надійшов для скасованого замовлення. Примітка пояснює причину. Перевірте замовлення і або виконайте його, або поверніть платіж на панелі Paymob.

Коли замовлення, яке вже має статус, змінюється, OpenCart повідомляє покупця. Якщо для вже оплаченого замовлення надходить другий успішний платіж або платіж за друге замовлення вже оплаченого кошика, оплачене замовлення не змінюється, а примітка просить повернути дублікат на панелі Paymob. Платіж за скасоване замовлення, яке раніше було оплачено, або за замовлення з поверненням коштів лише додає примітку: замовлення не відкривається знову. Відхилений платіж для замовлення, яке вже має статус, лише додає примітку.

Примітки — це записи в History замовлення, які покупець не бачить.

Вкладка VibeFox Paymob Pay

У Sales > Orders відкрийте замовлення, оплачене через Paymob. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox Paymob Pay показує кожну спробу Paymob для замовлення: Paymob order з ID замовлення мерчанта та країною, Paymob transaction ID, Status, запитувану суму Requested, Amount reported by Paymob з карткою та Paymob message. Нижче наведено Notes розширення для цього замовлення. Вкладка видима користувачам, які мають доступ до розширення.

Повернення коштів

Повернення коштів з адмін-панелі не підтримуються. Поверніть або анулюйте платіж на панелі Paymob. Коли Paymob повідомляє про повернення або анулювання, до замовлення додається примітка, а статус замовлення не змінюється. Оновіть замовлення вручну.

Ліцензійний ключ

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Paymob Pay — це перший блок у Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ з цього магазину. Нижче є рядок Product: opencart-payment-paymob і посилання 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.

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

Коли ліцензія спливає, розширення продовжує працювати, але оновлення та підтримка потребують продовження. Статус автоматично перевіряється знову, коли ви відкриваєте Dashboard або сторінку Edit адмін-панелі: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення розширення завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

Paymob не з'являється на оформленні замовлення: перевірте, чи ліцензія активна, чи увімкнено Enable/Disable, чи заповнені всі чотири значення (API-ключ, ID інтеграції, ID iFrame, секрет HMAC) і чи валюта оформлення — валюта вибраної Paymob country. Сторінка налаштувань показує попередження, коли чогось бракує. Також перевірте, чи адреса оплати входить до вибраної Geo Zone і чи замовлення досягає Total, заданого в налаштуваннях.

Платіж пройшов, але замовлення залишається без статусу: callback не доходять до вашого магазину. Перевірте, що Transaction processed callback і Transaction response callback використовуваної інтеграції точно збігаються з адресою з розділу Callbacks, і що HMAC secret — від того самого облікового запису Paymob. Відхилені callback записуються в журнал як попередження, навіть якщо Debug log вимкнено. Перегляньте поле Log на сторінці розширення.

Callback відповідає Invalid signature: секрет HMAC у налаштуваннях не збігається з обліковим записом Paymob, або вибрано обліковий запис іншої країни. Скопіюйте секрет HMAC знову.

Callback відповідає Not configured: секрет HMAC порожній. Введіть секрет; Paymob повторить callback.

Callback відповідає locked або retry: замовлення в той самий момент оновлював інший запит, наприклад повернення покупця, або не вдалося встановити статус замовлення. Paymob повторить callback. Причина записується в журнал.

Відкриття URL callback у браузері веде до оформлення з повідомленням про неможливість перевірки: це нормально. URL приймає лише підписані запити від Paymob.

Покупець бачить помилку після Confirm Order: увімкніть Debug log і перегляньте журнал. Paymob payments are temporarily unavailable означає неправильний API-ключ або відсутнє значення. Paymob could not start the payment означає, що Paymob відхилив запит, наприклад через неправильний ID інтеграції або неповні платіжні дані. This order cannot be paid with Paymob означає, що сума замовлення дорівнює нулю. Paymob does not accept payments in, за яким іде валюта, означає, що валюта замовлення не є валютою вибраної країни Paymob. This payment method is not available. означає, що сесія оформлення більше не відповідає замовленню або спосіб оплати тим часом вимкнули: покупець перезавантажує сторінку оформлення.

Замовлення в статусі «на утриманні» або очікування після оплати: прочитайте примітки у вкладці VibeFox Paymob Pay. Платіж очікує (готівка або кіоск), транзакцію лише авторизовано (спишіть її на панелі Paymob), сума або валюта не збіглися, або платіж надійшов після скасування замовлення.

Тестові платежі: введіть ID тестової інтеграції Paymob у Integration ID і задайте callback-URL у цій інтеграції. Для справжніх платежів введіть знову ID вашої робочої інтеграції.

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox Paymob Pay. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total і статуси замовлень у розділі Orders, які під час повторного встановлення повертаються до значень за замовчуванням. На OpenCart 4 також видаляються подія OpenCart цього розширення та його startup-дія, яка пропускає callback і повернення покупця в режимі обслуговування. Якщо Clean uninstall увімкнено, видаляються інші налаштування шлюзу (title, description, країна, ключі та ID, журналювання) і журнал. Якщо вимкнено, їх зберігають для повторного встановлення. Спроби оплати Paymob за замовленнями завжди зберігаються. Наявні замовлення зберігають свої примітки про оплату та ID Paymob.

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

Paymob — торгова марка її власника. Це розширення не пов'язане з Paymob і не схвалене Paymob.