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

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта: валюта кошика має бути SAR, AED, USD, EUR, KWD, BHD або OMR. Для будь-якої іншої валюти спосіб оплати приховується на етапі оформлення замовлення.

Обліковий запис Moyasar: потрібні секретні ключі API вашого облікового запису Moyasar (тестовий і робочий). Використовуються лише секретні ключі. Публічний ключ не потрібен, бо оплата відбувається на сторінці Moyasar. Рекомендовано вебхук у Moyasar Dashboard (див. розділ «Налаштування»).

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

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

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

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

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

4. Вставте секретні ключі Moyasar і натисніть Save. Налаштуйте вебхук у Moyasar Dashboard (див. розділ «Налаштування»).

5. Увімкніть Enable/Disable і натисніть Save. Оформіть тестове замовлення в тестовому режимі, після чого вимкніть Test mode.

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

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

Усі параметри розміщені на сторінці модуля: Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, коли для поточного режиму немає секретного ключа (тоді спосіб оплати приховується на етапі оформлення замовлення), коли не збережено спільний секрет вебхука (тоді вебхук відхиляє кожен виклик) або коли типова валюта магазину не підтримується. Поки модуль увімкнено в тестовому режимі, він показує Test mode is active: payments are simulated, no money is charged. Під час збереження модуль відхиляє публічний ключ, ключ іншого режиму або ключ із пробілами, зберігає попереднє значення та показує причину.

Moyasar

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

Title: назва способу оплати, яку бачить покупець на етапі оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Pay with Moyasar. Обов'язкове поле.

Description: текст, що відображається під способом оплати на етапі оформлення замовлення. За замовчуванням: You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. У тестовому режимі на етапі оформлення замовлення додається (Test mode: no real payment is made.)

API-ключі

Скопіюйте секретні ключі з розділу Moyasar Dashboard > Settings > API Keys. Тестові та робочі ключі окремі. Тестовий режим використовує лише тестовий ключ, робочий режим — лише робочий ключ.

Test mode: використовує тестовий секретний ключ: платежі імітуються, кошти не списуються. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі з робочим секретним ключем.

Test secret key: секретний ключ тестового режиму. Починається з sk_test_.

Live secret key: секретний ключ робочого режиму. Починається з sk_live_.

Збережені ключі та секрети більше не відображаються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Сповіщення про оплату (вебхук)

Вебхук рекомендовано, але не обов'язково. Замовлення також підтверджуються, коли покупець повертається до магазину, і через сповіщення про рахунок, яке Moyasar автоматично надсилає до вашого магазину після оплати рахунку. Вебхук охоплює покупців, які закрили браузер до повернення, і повідомляє про повернення, здійснені в Moyasar Dashboard. Додайте його в розділі Moyasar Dashboard > Settings > Webhooks.

Webhook URL: відображається лише для читання, з кнопкою Copy. Зі зрозумілими URL вона має такий вигляд: https://your-shop/module/wcp_moyasar_payment_gateway/webhook, можливо з кодом мови, наприклад /en/. Копіюйте URL точно так, як його показують налаштування. HTTP-метод: POST.

Webhook shared secret: введіть те саме значення, що й Shared secret вебхука в Moyasar. Якщо нічого не збережено, Save створює випадковий секрет; Generate a new secret замінює збережений. Створений секрет показується один раз над налаштуваннями після збереження і більше ніколи, тож одразу скопіюйте його в Moyasar. Вебхуки без правильного спільного секрету відхиляються.

Виберіть для вебхука такі події (вони також перелічені в цьому розділі):

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

Замовлення

Status after payment: статус замовлення, що встановлюється після підтвердженої оплати. Замовлення створюється одразу з цим статусом.

Додатково

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

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

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Pay with Moyasar) і підтверджує вибір. Модуль створює рахунок Moyasar на суму кошика у валюті кошика та надсилає покупця на його сторінку оплати. Там покупець сплачує будь-яким методом, активним у вашому обліковому записі Moyasar. Рахунок показує Order #, номер кошика та назву вашого магазину. На цьому етапі замовлення ще не існує.

Замовлення позначається оплаченим лише після підтвердження Moyasar: модуль отримує рахунок через API Moyasar і перевіряє, що він оплачений, належить цьому кошику та точно відповідає сумі й валюті кошика. Лише після цього створюється замовлення, і покупець бачить стандартну сторінку підтвердження з повідомленням Your payment with Moyasar has been received. Якщо Moyasar утримує платіж для перевірки, сторінка показує Your payment is being reviewed by Moyasar. The order will be updated automatically when Moyasar confirms it — please do not pay again. Якщо замовлення перебуває на утриманні для вашої перевірки, сторінка повідомляє, що платіж отримано і замовлення розглядається. Якщо платіж, що перевіряється, згодом не пройде або неоплачене замовлення буде скасовано, сторінка показує Your Moyasar payment was not completed. Please contact us about this order.

Якщо покупець повернувся без оплати (наприклад, кнопкою «Назад» на сторінці оплати), він опиняється на етапі оформлення замовлення з одним із повідомлень: The payment at Moyasar was not completed. You can try again or choose another payment method., Your Moyasar payment was declined or has expired. Please try again or choose another payment method. або, коли платіж ще не можна перевірити, We could not confirm your payment with Moyasar yet. If you completed the payment, the order will be updated automatically in a few minutes — please check your e-mail before paying again. Кошик зберігається.

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

Якщо Moyasar не може почати платіж, покупець залишається на етапі оформлення замовлення з коротким повідомленням, наприклад The Moyasar payment service is not responding. Please try again in a few minutes., і може обрати інший спосіб оплати. Деталі записуються в журнал.

Вебхук і сповіщення про рахунок працюють, коли магазин перебуває в режимі обслуговування, і не блокуються обмеженням за країнами вашого магазину.

Модуль приймає разові платежі лише на сторінці Moyasar. На вашому власному оформленні замовлення немає форми картки, збережених карток чи токенізації, підписок, а також окремих авторизації та списання.

Замовлення та повернення коштів

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

Замовлення ще немає: покупця відправили до Moyasar, і він не сплатив, або Moyasar ще не підтвердив платіж. Існує лише кошик.

Payment accepted, Delivered або Moyasar payment on hold: платіж підтверджено. Статус відповідає Status after payment. Платіж записується з ідентифікатором платежу Moyasar як ID транзакції, а примітка показує, як підтверджено платіж (вебхук, сповіщення про рахунок, повернення покупця або оформлення замовлення), ID рахунку, ID платежу та спосіб оплати.

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

Помилка оплати: платіж, що перевірявся, не пройшов.

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

Refunded: платіж повністю повернено через модуль.

Оплачене замовлення ніколи не повертається назад через пізніші події. Якщо другий рахунок за вже оплаченим кошиком також сплачено (наприклад, з двох вкладок браузера), замовлення не змінюється. Примітка просить вас повернути повторний платіж у Moyasar Dashboard.

Блок оплати Moyasar

Сторінка замовлення показує блок Moyasar payment з ідентифікатором рахунку Moyasar, ідентифікатором платежу, способом оплати (наприклад, маркою картки та останніми чотирма цифрами), статусом, сплаченою й поверненою сумами, позначкою Test mode для тестових платежів, історією повернень і Moyasar notes замовлення.

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

У блоці Moyasar payment введіть суму (підставляється сума, що ще не повернута), за бажанням причину, і натисніть Refund via Moyasar. Підтвердіть запитання Refund this amount through Moyasar? This cannot be undone. Підтримуються повні та часткові повернення. Потрібне право редагувати замовлення; доступ до сторінок модулів не потрібен. Повернення здійснюються в сумі та валюті, які списала Moyasar, тож після розбіжності суми можна повернути не більше того, що покупець фактично сплатив, а не суму замовлення. Повне повернення за карткою, сплаченою менш як 2 години тому, надсилається як анулювання (void): скасування до розрахунків, без комісій. В іншому разі це повернення. Повернення використовує секретний ключ того режиму, в якому здійснено платіж (тестовий або робочий), тож цей ключ має бути заданим. Модуль спершу перевіряє в Moyasar валюту, статус і суму платежу, доступну для повернення. Якщо Moyasar не приймає повернення, блок показує помилку, і повернення не записується. Успішне повернення або анулювання додається до історії повернень і приміток. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює. Повернення доступні після того, як Moyasar підтвердив платіж.

Модуль не створює кредитних нотаток. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають кошти через Moyasar.

Повернення та анулювання, здійснені в Moyasar Dashboard, надходять через вебхук. Якщо Moyasar показує більше повернутої суми, ніж записав модуль, до замовлення додається примітка. Статус замовлення та кредитні нотатки автоматично не змінюються. За потреби оновіть їх вручну, без використання Refund via Moyasar.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Moyasar Payment Gateway — перший блок на сторінці Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен) та кнопки Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього магазину. Нижче розміщені рядок Product: presta-payment-moyasar і посилання 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.

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

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

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

Moyasar не з'являється на етапі оформлення замовлення: перевірте, що ліцензія активна, що Enable/Disable увімкнено, що для поточного режиму є секретний ключ (Test secret key у тестовому режимі, Live secret key у робочому режимі) і що валюта кошика — SAR, AED, USD, EUR, KWD, BHD або OMR. Сторінка налаштувань показує попередження, коли ключа немає або валюта магазину не підтримується. У розділі Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: підтвердження не дійшли до вашого магазину. Налаштуйте вебхук: у Moyasar Dashboard перевірте, що він існує, що його URL точно збігається з Webhook URL у налаштуваннях, що метод — POST, що вибрано всі чотири події і що його спільний секрет дорівнює збереженому в Webhook shared secret. Замовлення також створюється, коли покупець повертається до магазину або намагається знову сплатити той самий кошик.

Вебхук відповідає Unauthorized: спільний секрет у Moyasar відрізняється від збереженого. Введіть секрет вебхука Moyasar у Webhook shared secret і збережіть, або позначте Generate a new secret, збережіть і вставте в Moyasar показаний секрет.

Вебхук відповідає Webhook secret not configured: спільний секрет не збережено, наприклад після видалення через Clear saved secrets. Натисніть Save, щоб створити його, і скопіюйте в Moyasar.

Вебхук відповідає Key not configured: рахунок створено в режимі (тестовому або робочому), для якого секретний ключ порожній. Введіть цей ключ.

Вебхук відповідає Verification failed або Try again later: рахунок не вдалося прочитати через API Moyasar, кошик у цей момент оновлював інший запит, або замовлення не вдалося створити (наприклад, модуль вимкнено). Moyasar повторить вебхук. Увімкніть Debug log, щоб побачити причину.

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

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

Покупець бачить помилку, обираючи Moyasar: увімкніть Debug log і перегляньте поле Log на сторінці модуля. This payment method is temporarily unavailable. Please choose another payment method or contact us. зазвичай означає неправильний або відсутній секретний ключ. A payment for this order has already been received and is being reviewed. Please contact us instead of paying again. означає, що в кошика вже є оплачений рахунок, який не вдалося перетворити на замовлення; перевірте журнал.

Order is Moyasar payment on hold after payment: прочитайте Moyasar notes у блоці Moyasar payment. Сплачені сума або валюта відрізнялися від кошика, або платіж надійшов після скасування замовлення. Виконайте замовлення або поверніть платіж.

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

Видалення

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

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