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

Вимоги

PrestaShop: 8.0–9.x.

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

Обліковий запис Razorpay: вам потрібні Key ID і Key Secret вашого облікового запису Razorpay для тестового режиму, а для робочого режиму — після активації облікового запису. Вебхук із секретом на ваш вибір наполегливо рекомендовано (див. Налаштування). Платежі у валютах, відмінних від INR, потребують увімкненої функції International Payments в обліковому записі Razorpay.

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

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

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

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

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

4. Введіть Test Key ID і Test Key Secret, налаштуйте вебхук у Razorpay Dashboard і введіть його секрет (див. Налаштування).

5. Увімкніть Enable/Disable і натисніть Save. Виконайте тестовий платіж з увімкненим Test mode. Коли все буде готово, введіть робочі ключі та вимкніть Test mode.

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

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

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Razorpay Payment > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує повідомлення: відсутні ключі поточного режиму (тоді Razorpay не відображається під час оформлення замовлення), Key ID не починається з rzp_test_ у тестовому режимі або з rzp_live_ у робочому, тестовий режим увімкнено, секрет вебхука порожній або основна валюта магазину не INR і потребує International Payments в обліковому записі Razorpay. Пробіли, вставлені разом із Key ID, видаляються під час збереження.

Razorpay

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

Title: назва способу оплати, яку бачить покупець під час оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: UPI, Cards, NetBanking. Обов'язкове поле: порожній заголовок дає помилку Enter a title for the payment method.

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

API-ключі

Ключі беруться в Razorpay Dashboard у розділі Account & Settings > API Keys. Переведіть Dashboard у тестовий режим, щоб згенерувати тестові ключі (rzp_test_...). Робочі ключі (rzp_live_...) доступні після активації облікового запису.

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

Test Key ID: Key ID з Razorpay Dashboard у тестовому режимі. Починається з rzp_test_.

Test Key Secret: Key Secret з Razorpay Dashboard у тестовому режимі.

Live Key ID: Key ID з Razorpay Dashboard у робочому режимі. Починається з rzp_live_.

Live Key Secret: Key Secret з Razorpay Dashboard у робочому режимі.

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

Очищення збережених секретів: позначте Test Key Secret, Live Key Secret або Webhook Secret і натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

Оплата

Payment Action: момент списання коштів. За замовчуванням: Authorize & Capture.

Authorize & Capture: покупець списується одразу. Якщо Razorpay повідомляє про авторизований платіж, модуль його захоплює.

Authorize Only: кошти резервуються. Замовлення створюється у статусі Razorpay payment authorized, а платіж ви захоплюєте пізніше через Capture Razorpay payment у блоці Razorpay на сторінці замовлення або в Razorpay Dashboard. Razorpay автоматично повертає авторизовані платежі, які не були захоплені вчасно.

Вебхук

Вебхук підтверджує платежі навіть тоді, коли покупець закриває браузер одразу після оплати, і фіксує повернення, зроблені в Razorpay Dashboard. У Razorpay Dashboard перейдіть до Account & Settings > Webhooks і додайте вебхук у тестовому режимі та ще один у робочому режимі. Використовуйте URL, який показано в полі Webhook URL у цьому розділі. З увімкненими зрозумілими URL він має такий вигляд: https://your-shop/module/wcp_razorpay_payment/webhook, можливо з кодом мови на кшталт /en/. Скопіюйте його точно так, як його показують налаштування. Введіть у Razorpay секрет на ваш вибір і виберіть такі події (вони також перелічені в цьому розділі):

payment.authorized: платіж авторизовано.

payment.captured: платіж захоплено, зокрема коли ви захоплюєте його в Razorpay Dashboard.

payment.failed: спроба платежу не вдалася.

order.paid: замовлення Razorpay, до якого належить платіж, оплачено.

refund.created: платіж повернуто, наприклад у Razorpay Dashboard.

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

Додатково

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

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

Delete Data on Uninstall: якщо увімкнено, під час видалення модуля його налаштування та журнал видаляються. Замовлення, транзакції та повернення Razorpay і статуси замовлень модуля завжди зберігаються. За замовчуванням: вимкнено.

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням UPI, Cards, NetBanking) і підтверджує вибір. Модуль створює замовлення Razorpay на точну суму кошика та його валюту і відкриває сторінку Razorpay payment вашого магазину. Спливаюче вікно Razorpay Checkout відкривається на цій сторінці автоматично, з уже заповненими іменем, e-mail і телефоном покупця. У Razorpay платіж відображається як Cart і номер кошика. На цьому етапі замовлення PrestaShop ще не існує. Якщо вікно закрито, покупець може натиснути Pay Now, щоб відкрити його знову, або Choose another payment method, щоб повернутися до оформлення замовлення. Кошик зберігається. У тестовому режимі сторінка показує Razorpay Test mode: no real money will be charged.

Після успішної оплати покупець бачить Please wait while we process your payment... Модуль перевіряє підпис Razorpay, отримує платіж через API Razorpay і порівнює суму та валюту з кошиком. Замовлення позначається оплаченим лише після підтвердження Razorpay. Потім замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення. Якщо підпис дійсний, але отримати платіж у цей момент не вдалося, замовлення створюється у статусі Razorpay payment on hold, а вебхук підтверджує його пізніше.

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

Повідомлення, які може побачити покупець:

Your session has expired. Please click "Pay Now" to try again.

We could not verify your payment. Повідомлення додає, що замовлення буде оновлено автоматично, щойно Razorpay підтвердить платіж, якщо кошти були списані.

This payment method is not available right now. Please choose another payment method. Ключі відсутні або неправильні.

Razorpay is temporarily unavailable. Please try again in a few minutes.

Razorpay could not accept this payment: далі вказано причину від Razorpay.

The order amount is too small to be paid with Razorpay.

Razorpay Checkout could not be loaded. Скрипт спливаючого вікна заблоковано; повідомлення просить перевірити з'єднання, вимкнути блокувальники контенту та перезавантажити сторінку.

Вебхук працює, коли магазин перебуває в режимі обслуговування, і не блокується обмеженням за країнами вашого магазину.

Модуль приймає лише разові платежі. Немає підписок і регулярних платежів, збережених карток, Razorpay Magic Checkout, Payment Links або Route (розділених платежів), а також віджетів пропозицій чи доступності платежу.

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

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

No order yet: покупець не оплатив, або Razorpay ще не підтвердив платіж. Існує лише кошик. Невдала спроба оплати не створює замовлення; покупець може оплатити знову.

Payment accepted: платіж захоплено та підтверджено. Платіж записується з ідентифікатором платежу Razorpay (pay_...) як ID транзакції, а примітка показує ID платежу, суму та спосіб підтвердження (callback, webhook, sync або admin).

Razorpay payment authorized: платіж лише авторизовано (Authorize Only). Захопіть його, щоб завершити замовлення.

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

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

Refunded: платіж повністю повернуто.

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

Блок оплати Razorpay

На сторінці замовлення показано блок Razorpay payment з ID платежу Razorpay, замовленням Razorpay, статусом платежу, Paid / refunded (сума, яку списав Razorpay, і повернена сума), позначкою Test mode для тестових платежів, історією повернень і Razorpay notes замовлення. Захоплення та повернення потребують права редагувати замовлення; доступ до налаштувань модуля не потрібен.

Захоплення (Authorize Only)

Відкрийте замовлення у статусі Razorpay payment authorized, натисніть Capture Razorpay payment у блоці Razorpay і підтвердіть. Платіж захоплюється в тому режимі, в якому його авторизовано, а замовлення переходить у статус Payment accepted. Якщо Razorpay відмовляє, блок і примітки показують Razorpay capture failed: із причиною. Захоплення, зроблене в Razorpay Dashboard, завершує замовлення через вебхук.

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

У блоці Razorpay введіть суму (підставляється сума, яку ще не повернуто), за бажанням причину, і натисніть Refund via Razorpay. Підтвердьте запитання Refund this amount through Razorpay? This cannot be undone. Підтримуються повні та часткові повернення. Повернення виконуються в сумі та валюті, які списав Razorpay, тому після розбіжності сум можна повернути не більше того, що покупець фактично сплатив, а не суму замовлення. Більша сума дає Invalid refund amount: at most і саму суму. Повернення надсилається ключами того режиму, у якому було здійснено платіж. Якщо Razorpay не приймає повернення, блок показує Razorpay refund failed: із причиною, і жодне повернення не фіксується. Успішне повернення додається до історії повернень і приміток із ID повернення Razorpay, сумою та статусом. Повне повернення переводить замовлення у статус Refunded. Часткове повернення статус не змінює. Повернення доступні після захоплення платежу.

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

Повернення, зроблені в Razorpay Dashboard, надходять через вебхук і фіксуються один раз в історії повернень та приміток. Коли замовлення повністю повернуто, його статус стає Refunded. Повернення з Dashboard в іншій валюті або більше за суму, доступну для повернення, автоматично не фіксується; примітка просить внести його вручну.

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

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

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

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

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

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

Платіж пройшов, але замовлення не створено: вебхук не працює. У Razorpay Dashboard перевірте, що вебхук існує в режимі, яким ви користуєтесь (Test або Live), що його URL точно збігається з показаним у Webhook URL і що вибрано всі п'ять подій. Перевірте, що Webhook Secret збігається із секретом у Razorpay. Замовлення також створюється, коли покупець повертається з вікна або знову починає оплату того самого кошика.

Вебхук відповідає Webhook secret not configured: Webhook Secret порожній. Введіть секрет вебхука Razorpay. Razorpay надішле подію повторно пізніше.

Вебхук відповідає Invalid signature або Missing signature: секрет у налаштуваннях відрізняється від секрету вебхука Razorpay. Введіть той самий секрет в обох місцях, для тестового та робочого вебхука.

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

URL вебхука в браузері показує Method not allowed: це нормально. URL приймає лише запити від Razorpay.

Замовлення має статус Razorpay payment on hold: прочитайте примітки в блоці Razorpay. Сума або валюта не збіглися з кошиком, платіж надійшов для скасованого замовлення, або його не вдалося перевірити через API Razorpay в цей момент, і він чекає на вебхук.

Покупець бачить помилку під час оплати: перегляньте поле Log на сторінці модуля. Помилки записуються навіть з вимкненим Enable Logging. Неправильні ключі дають повідомлення, що спосіб оплати наразі недоступний. Інші причини від Razorpay показуються після Razorpay could not accept this payment:.

Спливаюче вікно не відкривається: скрипт Razorpay Checkout заблоковано блокувальником контенту або з'єднанням. Покупець бачить повідомлення і може перезавантажити сторінку.

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

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Razorpay Payment і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete Data on Uninstall увімкнено, налаштування модуля та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для повторного встановлення. Транзакції та повернення Razorpay і статуси замовлень Razorpay payment authorized та Razorpay payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна й далі захоплювати та повертати після повторного встановлення. Наявні замовлення зберігають свої платіжні примітки та ID транзакцій.

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