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

Вимоги

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

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

Валюта: індійська рупія (INR). PayU India стягує кошти лише в рупіях. Для кошиків в інших валютах спосіб оплати приховано на етапі оформлення замовлення.

Номер телефону: PayU вимагає номер телефону для кожного платежу. Зробіть поле телефону в адресі обов'язковим або принаймні видимим у вашому оформленні замовлення.

Обліковий запис PayU India: потрібні Merchant Key та Merchant Salt (v1) з розділу PayU Dashboard > Payment Gateway > Key Salt Details. Переведіть панель у Test Mode, щоб побачити тестову пару. Використовуйте Salt v1, а не Salt v2.

Доступ магазину до інтернету: потрібен для необов'язкового вебхука. Без нього замовлення підтверджуються, коли покупець повертається від PayU.

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

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

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

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

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

4. Введіть Test Merchant Key і Salt та Live Merchant Key і Salt (див. Налаштування).

5. Рекомендовано: у PayU Dashboard > Webhooks додайте URL вебхука, який показано на сторінці Configure, для успішних і неуспішних платежів.

6. Оберіть Mode, увімкніть Enable/Disable і натисніть Save. Протестуйте платіж у тестовому режимі, потім перейдіть на робочий.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо немає ключа або salt поточного режиму, показує Test mode is active: payments go to test.payu.in and no real money is charged. у тестовому режимі та видає помилку, якщо валюта за замовчуванням вашого магазину не INR (тоді шлюз приховано на етапі оформлення замовлення).

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

PayU India

Enable/Disable: Enable PayU India Payment Gateway вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено. Якщо увімкнути його без ключа й salt поточного режиму, сторінка попередить вас після збереження.

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

Description: опис способу оплати, який покупець бачить під час оформлення замовлення. За замовчуванням: Pay securely via Credit/Debit Card, NetBanking, UPI, or Wallets through PayU.

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

Скопіюйте Merchant Key і Merchant Salt (v1) з розділу PayU Dashboard > Payment Gateway > Key Salt Details. Переведіть панель у Test Mode, щоб отримати тестову пару. У розділі є посилання Open the PayU Dashboard.

Mode: середовище PayU, яке використовують нові платежі.

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

Live Merchant Key: ваш робочий Merchant Key PayU.

Live Merchant Salt (v1): ваш робочий Merchant Salt (v1) PayU. Він підписує запити та перевіряє відповіді PayU. Тримайте його в таємниці.

Test Merchant Key: ваш тестовий Merchant Key PayU, використовується лише в тестовому режимі.

Test Merchant Salt (v1): ваш тестовий Merchant Salt (v1) PayU, використовується лише в тестовому режимі.

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

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

URL повернення та вебхука

Return URL: має вигляд https://your-shop/module/wcp_payu_india_payment/return, можливо, з кодом мови, наприклад /en/. Він автоматично передається в PayU з кожним платежем; нічого налаштовувати не потрібно.

Webhook URL: має вигляд https://your-shop/module/wcp_payu_india_payment/webhook, можливо, з кодом мови. Необов'язковий, але рекомендований: він підтверджує платежі, навіть якщо покупець закрив браузер до повернення. Додайте його в PayU Dashboard > Webhooks для успішних і неуспішних платежів. Копіюйте URL точно так, як його показано на сторінці Configure. Він має бути доступним з інтернету (без basic auth і без блокування брандмауером). Режим обслуговування магазину та обмеження за країнами його не блокують.

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

Додатково

Verify Payment: додатково перевіряє кожен успішний платіж через API verify_payment від PayU. Рекомендовано. Якщо перевірку не вдалося завершити, замовлення переводиться у статус «На утриманні», а не позначається як оплачене. За замовчуванням: увімкнено.

Enable Logging: записує події шлюзу для діагностики у файл logs/payu_p_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки та попередження записуються завжди; ця опція додає інші події, наприклад кожну платіжну форму та кожен результат PayU. Ключі, salt і персональні дані покупців ніколи не записуються. За замовчуванням: вимкнено.

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням PayU India) і підтверджує вибір. Якщо ні в адресі для рахунку, ні в адресі доставки немає номера телефону або мобільного, покупець залишається на етапі оформлення замовлення з повідомленням PayU India requires a phone number. Please enter your phone number and try again. Інакше він бачить коротку сторінку Thank you for your order. You will be redirected to PayU to complete your payment., яка надсилає підписаний платіжний запит на суму кошика на розміщену платіжну сторінку PayU. Якщо браузер не продовжує перехід сам, на сторінці є кнопка Pay with PayU і кнопка Back to checkout. На сторінці PayU покупець платить карткою, через NetBanking, UPI або електронний гаманець. На цьому етапі замовлення ще не існує.

Кожна спроба оплати отримує власний ідентифікатор транзакції PayU, який починається з номера кошика, і зберігається разом із сумою та режимом. Платіж, зроблений на попередній відкритій платіжній сторінці того самого кошика, все одно приймається. Для кошика, за яким уже є замовлення, нова платіжна форма не створюється, тож кнопка «Назад» у браузері не може розпочати другу оплату.

PayU повертає результат разом із покупцем і, якщо налаштовано, через вебхук. Результат приймається лише за наявності дійсного хешу PayU, згенерованого з ключем і salt того режиму, в якому було розпочато платіж, і лише для ідентифікатора транзакції, виданого для цього кошика. Якщо увімкнено Verify Payment, успішний результат додатково перевіряється через API verify_payment від PayU. Сплачена сума повинна збігатися із сумою спроби та сумою кошика з точністю до пайси, в INR. Замовлення позначається як оплачене лише після того, як PayU підтвердить це таким чином. Модуль обробляє такі результати PayU:

Після успішного або очікуваного платежу покупець бачить стандартну сторінку підтвердження замовлення. Очікуваний платіж додає повідомлення Your PayU payment is pending. The order will be updated as soon as PayU confirms the result — there is no need to pay again., замовлення на утриманні додає Your payment is being reviewed. We will contact you if anything else is needed., а замовлення у статусі Payment error або Canceled показує Your PayU payment was not completed. Please contact us about this order.

Після неуспішного платежу покупець повертається до оформлення замовлення з повідомленням: Payment was not completed. Please try again or choose a different payment method., Payment was cancelled. You may try again. або, якщо результат не вдалося перевірити, We could not confirm the payment result. If your account was charged, please contact us before paying again. Якщо результат ще обробляється, коли покупець повертається, з'являється сторінка з We are confirming your PayU payment. If you completed the payment, your order will be created shortly — please do not pay again. та кнопкою Check again.

Модуль стягує кошти виключно в INR і не підтримує мультивалютну обробку (MCP). У ньому немає збереження карток і токенізації, підписок, вбудованої форми картки на сайті (seamless), керування EMI чи спеціальними пропозиціями та швидкої оплати в один клік від PayU.

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

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

No order yet: покупця було перенаправлено до PayU, і він не оплатив, або платіж не пройшов чи був скасований. Існує лише кошик.

Payment accepted: платіж підтверджено. Платіж записується з ідентифікатором транзакції PayU (mihpayid) як ID транзакції, а примітка показує PayU payment successful. Transaction ID: …, Mode: …, Bank: …

Awaiting PayU India payment: платіж UPI або NetBanking ще очікує в PayU. Замовлення переходить у статус Payment accepted, коли PayU його підтвердить.

PayU India payment on hold: сплачена сума або валюта відрізняється від кошика, API verify_payment не вдалося викликати або він ще не підтвердив платіж, або надійшов платіж для замовлення, яке було скасовано. Примітка вказує причину. Перевірте транзакцію в PayU Dashboard, потім переведіть замовлення у статус Payment accepted або скасуйте його та поверніть платіж. Якщо не пройшла лише перевірка, замовлення оплачується автоматично під час наступної доставки результату.

Payment error: очікуваний платіж пізніше було відхилено або скасовано. Наступний успішний результат все одно оплачує замовлення.

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

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

Блок оплати PayU India

На сторінці замовлення є блок PayU India payment з ідентифікатором транзакції PayU (mihpayid), ідентифікатором транзакції магазину (txnid), середовищем, статусом PayU, режимом і банком платежу, сплаченою сумою та сумою запитаних повернень, значком Test mode для тестових платежів, історією повернень і примітками модуля. Для замовлення на утриманні показано нагадування перевірити платіж.

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

У блоці PayU India payment введіть суму (підставляється сума, яку ще не повернуто), за бажанням причину, і натисніть Refund via PayU. Підтвердьте запитання Refund this amount through PayU? This cannot be undone. Підтримуються повні та часткові повернення; сума має бути більшою за нуль і не перевищувати залишок того, що PayU стягнув. Потрібне право редагувати замовлення; доступ до сторінок модулів не потрібен. Повернення надсилається через API повернень PayU з ключем і salt того режиму, в якому було здійснено оплату, тож ці облікові дані мають бути задані. Якщо PayU відхиляє повернення, блок показує PayU refund failed: з повідомленням PayU, і повернення не реєструється.

PayU ставить повернення в чергу і виконує їх асинхронно; покупець зазвичай отримує гроші протягом 5–7 робочих днів. Історія повернень і примітки показують суму, ідентифікатор запиту PayU і причину. Повне повернення переводить замовлення у статус Refunded; часткове повернення статус не змінює. Повернення доступні, коли PayU повідомив ідентифікатор транзакції платежу. Модуль згодом не перевіряє статус повернення і не створює кредитні ноти. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають кошти через PayU.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox PayU India Payment Gateway — це перший блок на сторінці Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now, щоб перевірити статус ще раз, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розташовані рядок Product: presta-payment-payu-india і посилання 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 India не показується покупцям під час оформлення замовлення. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина магазину не знає, що ви увійшли в back office, тому спосіб оплати приховано і для вас: модуль можна налаштувати до купівлі ключа, але перевірити його під час оформлення замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Існуючі замовлення не зачіпаються: платежі, які вже розпочато, як і раніше підтверджуються сповіщеннями, а повернення працюють.

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

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

PayU India не відображається під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, а ключ і salt обраного Mode заповнені. Перевірте, що валюта кошика — INR, і що модулю дозволено цю валюту, країну покупця та його групу в Payment > Preferences. Сторінка Configure показує попередження про відсутні облікові дані та про валюту магазину, відмінну від INR.

Платіж пройшов, але замовлення не створено: покупець не повернувся до магазину, і вебхук не надійшов. Додайте URL вебхука зі сторінки Configure у PayU Dashboard > Webhooks для успішних і неуспішних платежів, і переконайтеся, що він доступний з інтернету.

Вебхук відповідає invalid_signature: хеш PayU не збігся. Перевірте, що ключ і salt режиму платежу правильні та використовується Salt v1, а не Salt v2. Результат робочого платежу, підписаний тестовим salt, або навпаки, також відхиляється. Нічого не змінюється.

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

Вебхук відповідає verify_unavailable: API verify_payment ще не зміг підтвердити платіж. Замовлення на утриманні, і наступна доставка перевірить знову.

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

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

Покупець бачить PayU India requires a phone number: зробіть поле телефону в адресі обов'язковим або видимим під час оформлення замовлення. Спочатку використовується адреса для рахунку, потім адреса доставки.

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

Повернення не проходить: PayU transaction ID not found for this order. означає, що в замовлення ще немає платежу PayU. This payment was made in Test mode, but the Merchant Key/Salt of that mode are not set. (або Live mode) означає, що спершу потрібно ввести облікові дані цього режиму. Invalid refund amount: at most … INR can be refunded. означає, що сума перевищує залишок платежу.

Замало інформації в журналі: помилки та попередження записуються завжди; увімкніть Enable Logging, щоб бачити також кожну платіжну форму та кожен результат PayU.

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

Видалення

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

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