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 отправляет уведомления. При ЧПУ-адресах он выглядит так: 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. E-mail, имя и телефон покупателя передаются в PayU. Язык страницы PayU соответствует языку магазина, если PayU его поддерживает, иначе используется английский. Покупатель переходит на страницу PayU, выбирает способ там и оплачивает. На этом этапе заказа ещё не существует.

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

Возврат в магазин сам по себе никогда не оплачивает заказ. Заказ отмечается оплаченным только после подтверждения PayU: уведомлением, подписанным Second Key среды платежа, либо серверной проверкой статуса заказа PayU при возвращении покупателя (не чаще раза в 10 секунд на корзину). Заказ PayU должен быть создан для этой корзины, сумма и валюта должны совпадать. Модуль обрабатывает следующие статусы PayU:

После подтверждённого платежа покупатель видит стандартную страницу подтверждения заказа. Для заказа, ожидающего подтверждения или находящегося на удержании, страница добавляет: Ваш платёж проверяется. Мы отправим вам e-mail, как только он будет подтверждён. Если платёж такого заказа позже отменяется, страница показывает: Ваш платёж 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.