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.