VibeFox Razorpay for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

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

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

Установка

1. В панели администратора перейдите в 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, настройте webhook в 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_ в рабочем, включён тестовый режим, секрет webhook пуст либо основная валюта магазина не 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.

Webhook

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

Webhook Secret: секрет, который вы ввели при создании webhook. Используйте один и тот же секрет для тестового и рабочего webhook, потому что в модуле для них одно поле. Webhook без действительной подписи отклоняется. Без webhook платёж подтверждается, только когда покупатель возвращается из всплывающего окна, или когда покупатель позже снова начинает оплату той же корзины.

Дополнительно

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, а webhook подтверждает его позже.

Если покупатель снова начинает оплату той же корзины, модуль использует свой заказ Razorpay повторно, когда сумма, валюта и режим не изменились. Если этот заказ Razorpay уже оплачен, например потому, что покупатель закрыл браузер и webhook отсутствует, модуль создаёт заказ по этому платежу, вместо того чтобы просить второй платёж. Если сумма корзины изменилась, создаётся новый заказ Razorpay.

Сообщения, которые может увидеть покупатель:

Webhook работает, когда магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

Модуль принимает только разовые платежи. Подписок и регулярных платежей, сохранённых карт, 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, завершает заказ через webhook.

Возвраты

В блоке 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. Частичный возврат статус не меняет. Возвраты доступны после списания платежа.

Модуль не создаёт credit slip (кредитные квитанции). Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Razorpay.

Возвраты, сделанные в Razorpay Dashboard, поступают через webhook и фиксируются один раз в истории возвратов и примечаниях. Когда заказ полностью возвращён, его статус становится 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 не знает, что вы вошли в панель администратора, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи продолжают подтверждаться, а списания и возвраты работают.

Когда лицензия истекает, модуль продолжает работать, но обновления и поддержка требуют продления. Статус автоматически проверяется, пока вы работаете в панели администратора: раз в день в течение первых 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

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

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

Webhook отвечает Webhook secret not configured: Webhook Secret пуст. Введите секрет webhook Razorpay. Razorpay отправит событие повторно позже.

Webhook отвечает Invalid signature или Missing signature: секрет в настройках отличается от секрета webhook Razorpay. Введите один и тот же секрет в обоих местах, для тестового и рабочего webhook.

Webhook отвечает Retry later: модулю не удалось подтвердить списание через API Razorpay, заказ не удалось создать (например, модуль отключён), или корзина в этот момент обновлялась другим запросом. Razorpay отправит событие автоматически. Причина указана в Log.

URL webhook в браузере показывает Method not allowed: это нормально. URL принимает только запросы от Razorpay.

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

Покупатель видит ошибку при оплате: посмотрите поле 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.