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

Вимоги

PrestaShop: 8.0–9.x.

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

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

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

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

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

1. У back office перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Paymob Pay у списку модулів і натисніть Configure.

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

4. Оберіть Paymob country і введіть API key, integration ID, iFrame ID та HMAC secret (див. Налаштування).

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

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

Під час встановлення модуль створює два статуси замовлення: Awaiting Paymob payment і Paymob payment on hold. PrestaShop за замовчуванням вмикає новий платіжний модуль для всіх валют, країн і груп клієнтів. Обмежити їх можна в Payment > Preferences. Країну, яку ви пізніше увімкнете в магазині, також потрібно позначити там для цього модуля.

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

Усі параметри розміщені на сторінці модуля: Modules > Module Manager > VibeFox Paymob Pay > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо бракує одного з чотирьох значень Paymob (до того часу Paymob приховано під час оформлення замовлення), і якщо обрана країна Paymob не приймає валюту магазину за замовчуванням. Блок Callbacks показує URL callback з кнопкою Copy і посиланням на панель Paymob обраної країни.

Paymob

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

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

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

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

Усі значення містяться на панелі мерчанта Paymob. Окремого тестового режиму немає: для тестових платежів введіть integration 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 key та HMAC secret більше ніколи не показуються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Clear saved secrets: позначте API key або HMAC secret і натисніть Save, щоб його видалити. Порожнє поле зберігає збережене значення.

Callbacks

Paymob повідомляє вашому магазину про кожну транзакцію. На панелі Paymob відкрийте Developers > Payment Integrations, оберіть свою інтеграцію, натисніть Edit і встановіть і Transaction processed callback, і Transaction response callback на URL з блоку Callbacks. З дружніми URL він має вигляд https://your-shop/module/wcp_paymob_pay/callback, можливо з кодом мови, наприклад /en/. URL формується мовою магазину за замовчуванням. Скопіюйте його кнопкою Copy. Встановіть URL в кожній інтеграції, яку ви використовуєте, включно з тестовою.

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

Додатково

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

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Paymob) і підтверджує. Модуль реєструє нове замовлення Paymob на суму кошика у валюті кошика, передає Paymob ім'я, e-mail, телефон і адресу для рахунку покупця та надсилає покупця на платіжну сторінку Paymob вашої країни. Там покупець платить одним із способів вашої інтеграції, наприклад карткою або мобільним гаманцем. На цьому етапі замовлення ще не існує.

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

Якщо замовлення в цей самий момент підтверджується callback Paymob, покупець бачить сторінку з текстом 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, тож покупець може оплатити кошик знову. Якщо відповідь від 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.

Якщо Paymob не може розпочати оплату, покупець залишається на оформленні замовлення з коротким повідомленням, наприклад 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. Немає збережених карток, підписок, вбудованої форми карток на вашому сайті та повернень із back office.

Замовлення

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

No order yet: покупця перенаправлено до Paymob, і він не оплатив, платіж відхилено або Paymob ще не підтвердив оплату. Існує лише кошик.

Payment accepted: Paymob підтвердив оплату. Платіж записується з ID транзакції Paymob як ID транзакції, а примітка показує транзакцію, суму та тип картки з останніми чотирма цифрами.

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

Paymob payment on hold: Paymob лише авторизував суму і не списав її (спишіть її на панелі Paymob; замовлення перейде в статус Payment accepted, коли надійде callback списання); або оплачена сума чи валюта відрізняються від кошика (наприклад, кошик змінили після початку оплати); або надійшов платіж для скасованого замовлення. Примітка пояснює причину. Перевірте замовлення та виконайте його або поверніть платіж на панелі Paymob.

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

Блок оплати Paymob

Сторінка замовлення показує блок Paymob payment з кожною спробою оплати Paymob для цього замовлення: замовлення Paymob, номер замовлення мерчанта та країна, ID транзакції Paymob, статус, запитувана сума, сума, яку Paymob повідомив за карткою, і повідомлення Paymob. Нижче розміщені Notes модуля для цього замовлення.

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

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

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Paymob Pay є першим блоком на сторінці Modules > Module Manager > VibeFox Paymob Pay > Configure, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ замаскованим, статус (наприклад, дату, до якої ліцензія дійсна, і ваш домен), а також кнопки Check now, щоб перевірити статус ще раз, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розміщені рядок Product: presta-payment-paymob і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові back office (включено англійську та російську).

Якщо ключ не приймається, блок показує причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on з датою. Після зміни адреси магазину або після звільнення слота домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль продовжує працювати з останнім відомим статусом.

Один ключ працює на одному домені: домені основного магазину, також у конфігурації з кількома магазинами. Видалення ключа з магазину не звільняє слот домену. Звільніть слот у своєму обліковому записі vibefox.net.

Без активного ключа Paymob не показується клієнтам під час оформлення замовлення. Якщо платіж все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви увійшли в back office, тому спосіб оплати приховано і для вас: ви можете налаштувати модуль до купівлі ключа, але не можете перевірити його на оформленні замовлення. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: уже розпочаті платежі й далі підтверджуються.

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

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

Paymob не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, усі чотири значення (API key, integration ID, iFrame ID, HMAC secret) заповнені, а валюта кошика — це валюта обраної Paymob country. Сторінка налаштувань показує попередження, коли чогось бракує. В Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни клієнта та групи клієнта.

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

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

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

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

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

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

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

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

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Paymob Pay і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Clean uninstall увімкнено, налаштування модуля та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для повторного встановлення. Спроби оплати Paymob за замовленнями та статуси замовлень Awaiting Paymob payment і Paymob payment on hold завжди зберігаються. Наявні замовлення зберігають свої примітки про оплату, ID транзакцій і ID Paymob.

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