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

Вимоги

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

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

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

Валюта магазину: одна з PLN, EUR, CZK, HUF, RON, BGN, GBP, USD, CHF, DKK, NOK, SEK, UAH. Валюта також повинна бути ввімкнена для вашої точки продажу в PayU. Для інших валют спосіб оплати приховується під час оформлення замовлення.

Доступ до вашого сайту з інтернету: PayU надсилає сповіщення про платежі до вашого магазину, тому сайт має бути доступним з інтернету (не закритий HTTP-автентифікацією чи сторінкою технічного обслуговування). Без сповіщень замовлення все одно перевіряються, коли покупець повертається з PayU.

Обліковий запис PayU: вам потрібні чотири ключі вашої точки продажу (POS): POS ID, Second key (MD5), OAuth client_id та OAuth client_secret. Вони розміщені в панелі продавця PayU в розділі Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. Ключі sandbox надаються в окремому обліковому записі sandbox PayU.

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

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

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

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

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

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

5. Введіть чотири ключі Sandbox і чотири ключі Live (дивіться розділ «Налаштування»). У PayU не потрібно налаштовувати URL сповіщень.

6. Увімкніть Enable/Disable. Залиште Test Mode увімкненим, доки не зробите тестовий платіж, потім зніміть позначку, щоб приймати справжні платежі за ключами Live.

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

Усі параметри розміщені на одній сторінці: WooCommerce > Settings > Payments > PayU. Поки активний режим sandbox, над полями відображається попередження, а також якщо відсутній один із чотирьох ключів поточного режиму або якщо PayU не підтримує валюту магазину. В останніх двох випадках PayU не показується під час оформлення замовлення.

Під час збереження пробіли та переноси рядків автоматично видаляються з усіх ключів, оскільки копіювання з панелі PayU часто додає їх.

Загальні

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

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

Description: опис способу оплати, який показується покупцеві. За замовчуванням: Pay securely via PayU.

Облікові дані API

Знайдіть ключі в панелі продавця PayU: Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. Ключі sandbox беруться з окремого тестового облікового запису sandbox PayU. Усі чотири ключі обраного режиму мають бути заповнені.

Test Mode: Enable sandbox (test) mode. Використовує пісочницю PayU та ключі Sandbox, зазначені нижче. Реальні кошти не списуються. У класичному оформленні замовлення та в блоці Checkout покупець бачить Sandbox mode — no real money is charged. Вимкніть його, щоб приймати справжні платежі з ключами Live. За замовчуванням: увімкнено.

Live POS ID: POS ID (merchantPosId) вашої робочої точки продажу.

Live Second Key (MD5): використовується для перевірки підпису сповіщень PayU.

Live OAuth Client ID: OAuth client_id точки продажу.

Live OAuth Client Secret: OAuth client_secret точки продажу.

Sandbox POS ID: POS ID вашої точки продажу в пісочниці PayU.

Sandbox Second Key (MD5): використовується для перевірки підпису сповіщень пісочниці PayU.

Sandbox OAuth Client ID: OAuth client_id тестової точки продажу.

Sandbox OAuth Client Secret: OAuth client_secret тестової точки продажу.

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

Сповіщення про платежі

У цьому розділі показано URL сповіщень, який виглядає як https://your-site/wc-api/wc_pu_payment/. Плагін надсилає його до PayU з кожним платежем, тому в панелі PayU нічого налаштовувати не потрібно. Переконайтеся, що він доступний з інтернету (не заблокований брандмауером, режимом обслуговування чи HTTP-автентифікацією).

Додатково

Receive payments automatically: Automatically receive payments waiting for confirmation. Це має значення лише тоді, коли автоматичне зарахування вимкнено для вашого POS у панелі PayU: у цьому випадку платежі очікують підтвердження (WAITING_FOR_CONFIRMATION). Якщо ця опція ввімкнена, плагін одразу приймає такі платежі. Якщо вона вимкнена, такі замовлення переводяться в статус «На утриманні», і ви приймаєте або скасовуєте платіж через дії замовлення Receive PayU payment та Cancel PayU payment. За замовчуванням: увімкнено.

Logging: Enable logging записує технічні події (номери замовлень, ID замовлень PayU, статуси, помилки; без ключів та персональних даних) у WooCommerce > Status > Logs, джерело wcp_payu_payment. За замовчуванням: вимкнено.

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

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

Покупець вибирає спосіб оплати (за замовчуванням PayU) і оформлює замовлення. Плагін створює замовлення PayU на загальну суму замовлення у валюті замовлення, з описом Order #, номером замовлення та назвою вашого магазину, а також із позиціями замовлення, доставкою та зборами для відображення на сторінці PayU. Мова сторінки PayU відповідає мові магазину, якщо PayU її підтримує, інакше — англійська. Покупець перенаправляється на платіжну сторінку PayU, вибирає спосіб і сплачує.

Кожна спроба оплати отримує власне замовлення PayU. Коли покупець сплачує повторно (після невдалого чи скасованого платежу або зі сторінки Pay for order), попередній незавершений платіж PayU для цього замовлення скасовується в PayU, тому старе посилання для оплати не можна оплатити двічі.

Саме лише повернення до вашого магазину ніколи не позначає замовлення оплаченим. Замовлення позначається оплаченим лише після підтвердження PayU: за сповіщенням, підписаним ключем Second Key середовища платежу, або за перевіркою статусу замовлення PayU на сервері під час повернення покупця (корисно, якщо сповіщення затримується). Замовлення PayU повинно бути створеним саме для цього замовлення, а сума та валюта мають збігатися. Плагін обробляє такі статуси PayU:

COMPLETED: платіж здійснено. Замовлення позначається оплаченим, якщо сума та валюта збігаються.

WAITING_FOR_CONFIRMATION: платіж авторизовано і він очікує на зарахування. Він приймається автоматично або через дії із замовленням, дивіться Receive payments automatically.

CANCELED: платіж було скасовано або відхилено. Неоплачене замовлення останньої спроби позначається як Не вдалося. Попередні спроби та оплачені замовлення не змінюються.

NEW, PENDING: платіж обробляється в PayU. Замовлення не змінюється.

На сторінці отриманого замовлення, доки воно перебуває в статусі Очікує оплати, покупець бачить We have not received the payment confirmation from PayU yet. If the payment was interrupted, you can try again: або після невдалого платежу — The payment was not completed. You can try again:, кожен із кнопкою Pay again. Для замовлення на утриманні повідомлення звучить так: Your payment is being verified. We will send you an e-mail as soon as it is confirmed.

Якщо PayU не може розпочати платіж, покупець бачить Payment error. Please try again or choose another payment method. Технічна причина (HTTP-код та статус PayU) записується в журнал і в примітку до замовлення PayU payment could not be started:. Якщо відсутні ключі поточного режиму, повідомлення звучить так: Payment gateway is not configured properly. Please contact the administrator.

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

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

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

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

Pending payment: покупець був спрямований до PayU і ще не здійснив оплату. Примітка до замовлення містить ID замовлення PayU та середовище (sandbox чи live).

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

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

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

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

Платежі, що очікують на підтвердження

Для неоплаченого замовлення з платежем, який очікує підтвердження, на екрані замовлення доступні дві дії: Receive PayU payment (waiting for confirmation) та Cancel PayU payment (release the funds). Виберіть одну з них і натисніть кнопку оновлення. Дія додається до приміток до замовлення з вашим іменем користувача, і новий статус PayU застосовується миттєво.

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

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

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

Замовлення, переведені в статус «На утриманні» через розбіжність у сумі чи валюті, зберігають ID замовлення PayU як ID транзакції, завдяки чому платіж можна повернути як із WooCommerce, так і в панелі PayU.

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

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

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

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

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

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

PayU не з'являється під час оформлення замовлення: перевірте, чи активна ліцензія, чи ввімкнено Enable/Disable і чи заповнено всі чотири ключі поточного режиму: ключі Sandbox у тестовому режимі, ключі Live у робочому. Перевірте, чи валюта магазину (або валюта замовлення на сторінці Pay for order) входить до списку підтримуваних. На сторінці налаштувань відображається попередження для кожної з цих проблем.

Платіж пройшов, але замовлення залишається в статусі Очікує оплати: PayU ще не доставив сповіщення, а перевірка статусу на сторінці повернення не зафіксувала завершеного платежу. Переконайтеся, що вказаний у налаштуваннях URL сповіщень доступний з інтернету. Увімкніть Logging, щоб переглянути дані, які надходять.

Сповіщення відповідає Invalid signature: сповіщення не було підписано ключем Second Key жодного із середовищ. Перевірте Live Second Key (MD5) та Sandbox Second Key (MD5). Відповідь Invalid signature for this payment означає, що сповіщення було підписано ключем іншого середовища, ніж те, де здійснювався платіж.

Сповіщення відповідає Ignored: замовлення PayU не належить жодному замовленню цього магазину, сплаченому через PayU, наприклад належить іншому магазину на тому самому POS. PayU припиняє повторні спроби.

Платіж не створюється: увімкніть Logging і перевірте WooCommerce > Status > Logs, джерело wcp_payu_payment. Журнал містить HTTP-код і статус PayU. Повідомлення Could not authenticate with PayU (check the OAuth client ID / secret). вказує на неправильні ключі OAuth для поточного режиму.

Замовлення має статус «На утриманні»: прочитайте примітку до замовлення. Причина криється в невідповідності суми чи валюти, платежі після скасування замовлення або платежі, що очікує підтвердження. В останньому випадку скористайтеся діями замовлення Receive PayU payment або Cancel PayU payment.

Помилка під час повернення коштів: This order has no completed PayU payment. Cannot process refund. означає, що замовлення не має оплаченого замовлення PayU. Повідомлення про відсутність ключів Sandbox або Live означає, що платіж здійснювався в тому середовищі, а його ключі не вказано. Введіть їх і спробуйте знову.

Інші валюти: розробники можуть змінити список валют за допомогою фільтра wc_pu_supported_currencies, а значок під час оформлення замовлення — за допомогою фільтра wc_pu_icon.

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

Видалення

Деактивація плагіна зберігає всі налаштування; очищаються лише кешовані токени доступу PayU. Щоб видалити його, деактивуйте та видаліть плагін на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються разом із кешованими токенами. Налаштування шлюзу та журнал цього плагіна видаляються лише в тому випадку, якщо було ввімкнено Delete data on uninstall. В іншому разі вони зберігаються для повторного встановлення пізніше. Наявні замовлення зберігають свої платіжні примітки, ID замовлень PayU та ID транзакцій.

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