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

Вимоги

WordPress: 6.2 або новіша версія.

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

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

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

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

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

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

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

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

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

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

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

6. У панелі керування Paymob вкажіть URL колбеків вашої інтеграції — той, що відображається на сторінці налаштувань (див. розділ Callbacks).

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

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

Усі налаштування розташовані на одній сторінці: WooCommerce > Settings > Payments > Paymob. Над полями сторінка попереджає, якщо бракує одного з чотирьох значень Paymob (доки їх немає, Paymob не відображається на сторінці оформлення замовлення), та якщо обрана країна Paymob не приймає валюту магазину. У блоці показано URL колбека з кнопкою Copy і посилання на панель керування Paymob обраної країни.

Загальні

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

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

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

Обліковий запис 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. Обов'язково: замовлення позначаються оплаченими лише за колбеками, підписаними цим секретом.

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

Callbacks

Paymob повідомляє вашому магазину про кожну транзакцію. У панелі керування Paymob відкрийте Developers > Payment Integrations, оберіть свою інтеграцію, натисніть Edit і вкажіть і в Transaction processed callback, і в Transaction response callback URL, що відображається на сторінці налаштувань. Він має такий вигляд: https://your-site/wc-api/paymob_pay/. Скопіюйте його кнопкою Copy. Вкажіть URL у всіх інтеграціях, які ви використовуєте, зокрема в тестовій.

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

Додатково

Debug log: Log payment steps and callbacks записує кроки оплати та колбеки в WooCommerce > Status > Logs, джерело wcp_paymob_pay. Помилки та відхилені колбеки записуються завжди. Ключі, токени й дані покупців ніколи не записуються. За замовчуванням: вимкнено.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Деактивація плагіна нічого не видаляє. ID Paymob, збережені в замовленнях, залишаються. За замовчуванням: вимкнено.

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

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

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

Якщо платіж відхилено, покупець повертається до оформлення замовлення (або на сторінку Pay for order, якщо оплату було розпочато там) з повідомленням 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. Технічна причина записується в журнал.

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

Плагін приймає одноразові платежі на сторінці Paymob. У ньому немає збережених карток, підписок, вбудованої форми картки на вашому сайті та повернень із WooCommerce.

Замовлення

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

Pending payment: покупця було перенаправлено до Paymob, і він ще не оплатив, або Paymob ще не підтвердив платіж.

Processing: Paymob підтвердив оплату. Замовлення, що містять лише віртуальні товари для завантаження, переходять у статус Виконано — значення WooCommerce за замовчуванням. У примітці до замовлення вказано транзакцію Paymob, суму та тип картки з останніми чотирма цифрами. ID транзакції — це ID транзакції Paymob.

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

Failed: Paymob відхилив платіж для замовлення, що очікує оплати. Покупець може оплатити знову.

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

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

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

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

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

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

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

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

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

Paymob не відображається на сторінці оформлення замовлення: переконайтеся, що ліцензія активна, Enable/Disable увімкнено, усі чотири значення (API key, Integration ID, iFrame ID, HMAC secret) заповнені, а валюта магазину є валютою обраного Paymob country. Сторінка налаштувань показує попередження, якщо щось бракує. Розробники з обліковим записом Paymob для кількох валют можуть розширити список прийнятних валют фільтром paymob_p_supported_currencies.

Платіж пройшов, але замовлення залишається у статусі Pending payment: колбеки не доходять до вашого магазину. Перевірте, що Transaction processed callback і Transaction response callback використовуваної інтеграції точно збігаються з URL на сторінці налаштувань, а HMAC secret належить тому самому обліковому запису Paymob. Відхилені колбеки записуються як попередження в WooCommerce > Status > Logs, джерело wcp_paymob_pay, навіть якщо журнал налагодження вимкнено.

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

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

Колбек відповідає locked: замовлення в цей момент оновлював інший запит, наприклад повернення покупця. Paymob повторить колбек.

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

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

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

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

Видалення

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

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