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

Вимоги

WordPress: 6.0 або новішої версії.

WooCommerce: 8.0 або новішої версії, встановлений і активний. За старішої версії WooCommerce плагін показує сповіщення і не завантажується.

PHP: 8.0 або новішої версії.

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

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

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

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, оберіть ZIP-файл плагіна та натисніть Install Now. Також можна завантажити папку wcp_moyasar_payment_gateway до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Moyasar > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії вгорі сторінки та натисніть Activate.

5. Вставте секретні ключі Moyasar і збережіть. Налаштуйте вебхук у Moyasar Dashboard з URL та спільним секретом, які відображаються в налаштуваннях (див. Налаштування).

6. Увімкніть Enable/Disable. Зробіть тестове замовлення в тестовому режимі, а потім зніміть позначку з Test mode.

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

Усі налаштування розташовані на одній сторінці: WooCommerce > Settings > Payments > Moyasar. Заголовок сторінки показує позначку TEST MODE або LIVE. Над полями сторінка попереджає, якщо для поточного режиму немає секретного ключа (тоді спосіб оплати приховується під час оформлення замовлення) або валюта магазину не підтримується, а також показує 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: Enable test mode використовує тестовий секретний ключ: платежі імітуються, кошти не списуються. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі з робочим секретним ключем.

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

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

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

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

Webhook URL: відображається лише для читання, з кнопкою Copy. Має вигляд на зразок https://your-site/wp-json/moyasar_p/v1/webhook. Метод HTTP: POST.

Webhook shared secret: введіть те саме значення, що й Shared secret вебхука в Moyasar. Залиште поле порожнім і збережіть, щоб згенерувати випадковий секрет, потім натисніть Show і скопіюйте його в Moyasar. Вебхуки без правильного спільного секрету відхиляються.

Оберіть для вебхука такі події:

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

Замовлення

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

Додатково

Debug log: Log API calls and notifications записує деталі до WooCommerce > Status > Logs, джерело wcp_moyasar_payment_gateway. Помилки записуються завжди. Ключі API, дані картки та покупця ніколи не записуються. За замовчуванням: вимкнено.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Платіжні дані, збережені в замовленнях (ідентифікатори рахунку та платежу Moyasar), зберігаються, щоб повернення коштів можна було відстежити. За замовчуванням: вимкнено.

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

Покупець обирає спосіб оплати (за замовчуванням Pay with Moyasar) і оформлює замовлення. Плагін створює рахунок Moyasar на суму замовлення у валюті замовлення та надсилає покупця на сторінку оплати. Там покупець сплачує будь-яким методом, активним у вашому обліковому записі Moyasar, наприклад mada, Visa, Mastercard, Apple Pay або STC Pay. У рахунку відображаються Order, номер замовлення та назва вашого сайту.

Замовлення позначається як оплачене лише після підтвердження Moyasar: плагін зчитує рахунок через API Moyasar і перевіряє, що його сплачено, що він належить цьому замовленню та має точно таку саму суму і валюту, як замовлення. Після оплати покупець повертається на сторінку «Замовлення отримано» вашого магазину. Якщо покупець повернувся без оплати (наприклад, кнопкою «Назад» на сторінці оплати), він потрапляє назад до оформлення замовлення або на сторінку Pay for 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 не може розпочати оплату, покупець бачить коротке повідомлення, наприклад The Moyasar payment service is not responding. Please try again in a few minutes., і може обрати інший спосіб оплати. Подробиці записуються в журнал.

Спосіб оплати працює на класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний із WooCommerce High-Performance Order Storage (HPOS).

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

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

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

Pending payment: рахунок створено, а покупець ще не сплатив. У примітці до замовлення вказано ідентифікатор рахунку, суму та режим.

Processing, Completed or On hold: оплату підтверджено. Статус відповідає налаштуванню Status after payment. У примітці до замовлення вказано, як підтверджено оплату (вебхук, сповіщення про рахунок, повернення покупця або оформлення замовлення), ідентифікатор рахунку, ідентифікатор платежу та спосіб оплати. Ідентифікатор транзакції — це ідентифікатор платежу Moyasar.

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

On hold before payment: Moyasar утримує платіж для перевірки. Замовлення оновиться, коли Moyasar ухвалить рішення.

Failed: останній рахунок неоплаченого замовлення було відхилено, він прострочений або скасований. Покупець може спробувати оплатити знову.

Cancelled: замовлення скасовано покупцем, вами або через тайм-аут резервування запасів WooCommerce. Відкритий рахунок Moyasar для замовлення також скасовується, тож його вже не можна сплатити.

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

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

Відкрийте замовлення, натисніть Refund, введіть суму та натисніть Refund via Pay with Moyasar (кнопка використовує назву способу оплати). Повні та часткові повернення підтримуються для замовлень із платежем Moyasar. Повне повернення за карткою, сплаченою менш як 2 години тому, надсилається як анулювання (скасування до розрахунку); в інших випадках це повернення. Повернення використовує секретний ключ режиму, в якому було здійснено оплату (тестовий або робочий), тому цей ключ має бути заданий. Перед поверненням плагін перевіряє платіж у Moyasar: його валюту, статус і суму, яку ще можна повернути. Якщо Moyasar не приймає повернення, WooCommerce показує помилку, і повернення не реєструється. Успішне повернення або анулювання додається до приміток замовлення.

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

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташований угорі WooCommerce > Settings > Payments > Moyasar. Вставте ключ у License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, і ваш домен. Використовуйте Check now, щоб повторно перевірити статус, Change key, щоб ввести інший ключ, і Remove key, щоб видалити його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

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

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

Коли термін ліцензії спливає, плагін продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову у фоновому режимі.

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

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

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

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

Вебхук відповідає Webhook secret not configured: налаштування ще не збережено зі спільним секретом. Збережіть налаштування, щоб його згенерувати, і скопіюйте його в Moyasar.

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

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

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

Покупець бачить помилку під час оформлення замовлення: увімкніть Debug log і перегляньте WooCommerce > Status > Logs, джерело wcp_moyasar_payment_gateway. 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. означає, що в замовлення вже є оплачений рахунок, який потребує вашої перевірки.

Замовлення має статус On hold after payment: прочитайте примітку до замовлення. Сплачена сума або валюта відрізнялися від замовлення, або платіж надійшов після скасування замовлення. Виконайте замовлення або поверніть кошти.

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

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть місце у своєму обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін працює з останнім відомим статусом.

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування шлюзу та журнали видаляються лише тоді, коли було увімкнено Clean uninstall. Інакше вони зберігаються для повторного встановлення. Наявні замовлення зберігають свої платіжні примітки та ідентифікатори транзакцій.

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