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

Вимоги

PrestaShop: від 8.0 до 9.x.

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

Валюта: одна з 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. У back office перейдіть до Modules > Module Manager і натисніть Upload a module. Виберіть ZIP-файл модуля.

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

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

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

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

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

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

Усі налаштування розміщені на сторінці модуля: Modules > Module Manager > VibeFox PayU Payment > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, поки ввімкнено режим sandbox (Режим sandbox (тестовий) увімкнено: платежі йдуть до sandbox PayU, реальні кошти не списуються. Не відправляйте замовлення, оплачені в тестовому режимі.), коли відсутній один із чотирьох ключів поточного режиму, і коли PayU не приймає валюту магазину за замовчуванням. У двох останніх випадках PayU не показується під час оформлення замовлення.

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

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: використовує sandbox PayU і ключі Sandbox нижче. Реальні кошти не списуються. Поки режим увімкнено, покупці бачать під варіантом оплати Режим sandbox: реальний платіж не проводиться. Вимкніть, щоб приймати реальні платежі ключами Live. За замовчуванням: увімкнено.

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

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

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

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

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

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

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

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

Збережені Second Key і client secret більше не відображаються. Поле залишається порожнім і показує Збережено — залиште порожнім, щоб зберегти. Вводьте нове значення, лише якщо хочете його змінити. POS ID і client ID відображаються як збережені.

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

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

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

Notification URL: показує адресу, на яку PayU надсилає сповіщення. З дружніми URL вона має вигляд https://your-shop/module/wcp_payu_payment/webhook, можливо, з кодом мови. Модуль передає її в PayU з кожним платежем, тому в панелі PayU нічого налаштовувати не потрібно. Переконайтеся, що вона доступна з інтернету (не заблокована брандмауером чи HTTP-автентифікацією). Сповіщення працюють і тоді, коли магазин у режимі обслуговування, і не блокуються обмеженням за країнами вашого магазину.

Додатково

Receive payments automatically: автоматично приймає платежі, що очікують підтвердження. Це важливо лише тоді, коли автоматичний прийом вимкнено для вашої точки продажу в панелі PayU: тоді платежі очікують підтвердження (WAITING_FOR_CONFIRMATION). Якщо опцію увімкнено, модуль одразу приймає такі платежі, а замовлення створюється, коли PayU повідомляє про завершення платежу. Якщо вона вимкнена або прийом не вдався, замовлення створюється у статусі Awaiting PayU payment confirmation, а ви приймаєте або скасовуєте платіж кнопками в блоці PayU замовлення. За замовчуванням: увімкнено.

Logging: записує технічні події (номери кошиків і замовлень, ID замовлень PayU, статуси, помилки; без ключів і персональних даних) у logs/wc_pu_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки записуються завжди; інші події — лише поки опцію увімкнено. За замовчуванням: вимкнено.

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

Delete data on uninstall: видаляє налаштування та журнали модуля під час його видалення. Замовлення та їх платіжні дані (транзакції PayU, повернення, статуси замовлень) ніколи не видаляються. За замовчуванням: вимкнено.

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

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

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

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

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

Якщо PayU ще не підтвердив платіж, коли покупець повертається, сторінка Payment confirmation показує: Ми ще не отримали підтвердження платежу від PayU. Якщо оплату було перервано, ви можете спробувати знову: (або, якщо PayU повідомив про помилку, Платіж не було завершено. Ви можете спробувати знову:) з кнопками Pay again і Check again. Сповіщення створює замовлення, щойно воно надходить. Якщо платіж скасовано, покупець повертається до оформлення замовлення з повідомленням Платіж не було завершено. Ви можете спробувати знову або обрати інший спосіб оплати. Кошик зберігається.

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

Якщо ваучер у кошику перестає бути дійсним між оплатою та її підтвердженням, він видаляється із замовлення. Замовлення тоді переходить у статус PayU payment on hold з приміткою, у якій зазначено ваучер, оскільки покупець сплатив ціну зі знижкою.

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

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

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

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

Payment accepted: платіж підтверджено. Він записується з ID замовлення PayU як ID транзакції, а примітка показує ID замовлення PayU, суму та середовище (sandbox або live).

Awaiting PayU payment confirmation: платіж авторизовано і очікує вашого рішення (автоматичний прийом вимкнено або не вдався). Платіж поки не записано.

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

Payment error: платіж замовлення, що очікувало підтвердження, було скасовано або відхилено.

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

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

Блок платежу PayU

На сторінці замовлення є блок PayU payment з ID замовлення PayU, extOrderId, статусом PayU, сплаченою та поверненою сумою, позначкою Sandbox для платежів sandbox, історією повернень і PayU notes замовлення. Дії блоку потребують права редагувати замовлення; доступ до сторінок модулів не потрібен.

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

Для замовлення з платежем, що очікує підтвердження, блок показує Receive PayU payment (waiting for confirmation) і Cancel PayU payment (release the funds). Після підтвердження питання дію надсилають до PayU з ключами середовища платежу, додають до приміток з вашим іменем, і новий статус PayU застосовується одразу: прийнятий платіж переводить замовлення в Payment accepted, скасований — у Payment error.

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

У блоці PayU payment введіть суму (підставляється сума, яку ще не повернуто), за бажанням причину, і натисніть Refund via PayU. Підтвердьте питання Повернути цю суму через PayU? Цю дію неможливо скасувати. Підтримуються повні та часткові повернення. Повернення надсилається для фактично оплаченого замовлення PayU з ключами середовища платежу, тому ці ключі мають бути заповнені. Повернення виконуються в сумі та валюті, списаних PayU, тому після розбіжності суми або валюти можна повернути не більше того, що фактично сплатив покупець, а не суму замовлення. Причина надсилається як опис повернення. Якщо PayU відхиляє повернення, блок показує помилку PayU, і повернення не записується. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює.

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

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

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

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

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

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

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

PayU не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і заповнені всі чотири ключі поточного режиму: ключі Sandbox у режимі sandbox, ключі Live у робочому режимі. Перевірте, що валюта кошика входить до підтримуваних. У Payment > Preferences перевірте, що модулю дозволено валюту кошика, країну покупця та групу покупця. Сторінка налаштувань показує попередження, коли ключі відсутні або валюта магазину не підтримується.

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

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

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

Сповіщення відповідає Busy, retry later: кошик у цей самий час підтверджувався іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). PayU повторює сповіщення. Увімкніть Logging, щоб побачити причину.

URL сповіщень показує POST expected у браузері: це нормально. URL приймає лише сповіщення від PayU.

Покупець бачить Payment error під час вибору PayU: увімкніть Logging і перегляньте поле Log на сторінці модуля. У журналі буде HTTP-код і статус PayU. Не вдалося автентифікуватися в PayU (перевірте OAuth client ID / secret). означає неправильні ключі OAuth поточного режиму.

Замовлення має статус PayU payment on hold: прочитайте примітки в блоці PayU payment (див. Статуси замовлень), потім виконайте замовлення або поверніть платіж.

Замовлення має статус Awaiting PayU payment confirmation: автоматичний прийом для вашої точки продажу вимкнено, і платіж очікує на вас. Використовуйте Receive PayU payment або Cancel PayU payment у блоці PayU.

Повернення не виконується: Для цього замовлення немає завершеного платежу PayU. Неможливо обробити повернення. означає, що PayU ще не завершив платіж за замовленням. Повідомлення про відсутність ключів Sandbox або Live означає, що платіж було зроблено в цьому середовищі, а його ключі не заповнені. Введіть їх і спробуйте знову.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox PayU Payment і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Кешовані токени доступу PayU завжди видаляються. Якщо Delete data on uninstall увімкнено, налаштування модуля та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для повторного встановлення. Транзакції та повернення PayU, а також статуси замовлень Awaiting PayU payment confirmation і PayU payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Існуючі замовлення зберігають свої платіжні примітки та ID транзакцій.

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