VibeFox PayU LATAM for WooCommerce — Помощь

Требования

WordPress: 5.8 или новее.

WooCommerce: 7.0 или новее, установлен и активен. Без него плагин не активируется; если WooCommerce впоследствии отключить, плагин ничего не делает и показывает уведомление в панели управления.

PHP: 8.0 или новее.

Currency: заказ должен быть в ARS, BRL, CLP, COP, MXN, PEN или USD — валютах, обрабатываемых PayU Latam в Аргентине, Бразилии, Чили, Колумбии, Мексике, Панаме и Перу. Для других валют способ оплаты скрывается при оформлении заказа.

PayU Latam account: нужны три значения вашего магазина в PayU: идентификатор мерчанта, идентификатор счёта страны продаж и ключ API. Они находятся в модуле PayU (панели мерчанта PayU), в разделах Settings > Technical configuration (идентификатор мерчанта, ключ API) и Accounts (идентификатор счёта). Для тестирования PayU публикует общедоступные тестовые учётные данные и тестовые карты на странице "Test your solution" документации для разработчиков. API Login и другие учётные данные API не нужны, поскольку оплата проходит на странице PayU.

Internet access to your site: PayU отправляет результат платежа в магазин со своих серверов, поэтому сайт должен быть доступен из интернета (не локальный сайт, не за паролем и не за страницей технического обслуживания).

VibeFox license key: приобретается на vibefox.net. Один ключ работает на одном домене.

Установка

1. В WordPress откройте Plugins > Add New > Upload Plugin, выберите ZIP-архив плагина и нажмите Install Now. Также можно загрузить папку wcp_payu_latam_payment в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > PayU LATAM > Manage, либо нажмите Settings под названием плагина на странице плагинов.

4. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

5. Введите учётные данные тестовой и рабочей среды (см. «Настройка»). Настраивать URL подтверждения в PayU не требуется.

6. Включите Enable/Disable и сохраните. Оставьте Sandbox включённым, пока не проведёте тестовый платёж, затем снимите флажок, чтобы принимать реальные платежи с рабочими учётными данными.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > PayU LATAM. Над полями показываются предупреждения о включённой тестовой среде (Sandbox mode. Платежи направляются в тестовую среду PayU, реальные деньги не списываются.), об отсутствии идентификатора мерчанта, идентификатора счёта или ключа API текущей среды и о том, что PayU LATAM не обрабатывает валюту магазина. В последних двух случаях PayU LATAM не показывается при оформлении заказа. В списке способов оплаты PayU LATAM помечается как требующий настройки, пока не заполнены все три значения учётных данных текущей среды. Пробелы в начале и конце значений игнорируются.

Общие настройки

Enable/Disable: Enable PayU LATAM включает или отключает способ оплаты. По умолчанию: off.

Title: название способа оплаты, которое покупатель видит при оформлении заказа. По умолчанию: PayU LATAM.

Description: описание способа оплаты, которое покупатель видит при оформлении заказа. По умолчанию: Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

Среда

Sandbox: Enable the PayU sandbox (test mode). Платежи направляются в тестовую среду PayU с указанными ниже тестовыми учётными данными, реальные деньги не списываются. При отключении используются рабочие учётные данные и рабочая страница оплаты PayU. По умолчанию: on.

Учётные данные рабочей среды

Найдите их в модуле PayU: Settings > Technical configuration (идентификатор мерчанта, ключ API) и Accounts (идентификатор счёта страны продаж). Раздел содержит ссылку на панель мерчанта PayU.

Merchant ID: числовой идентификатор вашего магазина в PayU.

Account ID: идентификатор счёта PayU. Для каждой страны используется отдельный счёт.

API Key: секретный ключ для подписи платежей и проверки уведомлений PayU.

Учётные данные тестовой среды

PayU публикует общедоступные тестовые учётные данные и карты для своей тестовой среды. Раздел содержит ссылку на страницу "Test your solution" документации PayU.

Sandbox merchant ID: идентификатор мерчанта тестовой среды PayU.

Sandbox account ID: идентификатор счёта тестовой среды PayU.

Sandbox API key: ключ API тестовой среды PayU.

Каждая попытка оплаты запоминает свою среду. Подтверждение тестового платежа проверяется с тестовыми ключом API и идентификатором мерчанта, а рабочего — с рабочими, поэтому ожидающие платежи продолжают обрабатываться после переключения. При обновлении с версии 1.0, где был один набор учётных данных, старые значения копируются в поля тестовой среды, если она была включена. Проверьте настройки после обновления.

URL подтверждения

Этот раздел показывает URL, на который PayU сообщает результат каждого платежа. Он выглядит так: https://your-site/wc-api/payu_lp/. Плагин передаёт его PayU с каждым платежом, поэтому в PayU ничего настраивать не нужно. Страница должна быть доступна из интернета. PayU подписывает подтверждение вашим ключом API. Подтверждения без действительной подписи, с другим идентификатором мерчанта или с платёжной ссылкой-идентификатором, которую магазин не создавал для заказа, отклоняются. Плагин обрабатывает следующие состояния транзакций PayU:

Остальные состояния только добавляются в заметку к заказу. Без подтверждения заказ никогда не отмечается оплаченным: он остаётся в статусе «Ожидание оплаты».

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

Debug log: Log payment requests and PayU notifications записывает подробности в WooCommerce > Status > Logs, источник wcp_payu_latam_payment, без ключей и персональных данных. Ошибки и отклонённые уведомления записываются всегда. По умолчанию: off.

Delete data: Delete the settings and logs when the plugin is deleted. Отключение плагина никогда ничего не удаляет. Данные PayU, сохранённые в заказах, остаются. По умолчанию: off.

Оформление заказа

Покупатель выбирает способ оплаты (по умолчанию PayU LATAM) и оформляет заказ. В блоке «Оформление заказа» в тестовой среде покупатель видит Sandbox mode: no real payment is made. Заказ остаётся в статусе «Ожидание оплаты», а покупатель переходит на платёжную страницу магазина с текстом Thank you for your order. You are being redirected to PayU LATAM to complete the payment… Страница автоматически отправляет подписанную форму на страницу PayU WebCheckout. Если этого не произошло, покупатель нажимает Pay with PayU LATAM или Cancel order для отмены заказа.

Форма содержит итоговую сумму и валюту заказа, налог и налоговую базу заказа (оба значения 0 для заказов без налога, чтобы PayU не добавлял НДС по умолчанию), описание Order # с номером заказа и названием магазина, электронную почту, имя, телефон и платёжный адрес покупателя. Страница PayU открывается на испанском, португальском или английском в зависимости от языка магазина. На странице PayU покупатель оплачивает любым способом, включённым в вашей учётной записи PayU.

Каждое посещение платёжной страницы создаёт новую попытку оплаты со своей ссылкой-идентификатором (номер заказа и метка времени). Сохраняются последние 30 попыток заказа: если покупатель оплатит в старой вкладке PayU, платёж всё равно принимается.

Заказ отмечается оплаченным только после подписанного подтверждения PayU. Возвращение покупателя из PayU никогда не отмечает заказ оплаченным. Когда покупатель возвращается:

Если учётные данные текущей среды отсутствуют, покупатель видит PayU LATAM is not available right now. Please choose another payment method. Для неподдерживаемой валюты заказа выводится PayU LATAM does not accept payments in, а затем валюта. Уже оплаченный заказ не оплачивается повторно: платёжная страница показывает This order has already been paid.

Способ оплаты работает на классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Совместим с WooCommerce High-Performance Order Storage (HPOS).

В плагине нет платёжной формы в магазине, возвратов из WooCommerce, сохранённых карт, подписок и настроек рассрочки (PayU показывает рассрочку на своей странице). Он не запрашивает статус платежа через API PayU: заказ обновляется только по подписанному подтверждению.

Заказы

Статусы заказов

Pending payment: покупатель отправлен в PayU и ещё не оплатил, либо PayU ещё не отправил подтверждение.

Processing: PayU подтвердил платёж, сумма и валюта совпадают. В заметке к заказу указаны транзакция PayU, сумма, способ оплаты и [sandbox] для тестовых платежей. Идентификатор транзакции заказа совпадает с идентификатором транзакции PayU. Заказы только с виртуальными скачиваемыми товарами получают статус «Выполнен», как предусмотрено WooCommerce по умолчанию.

On hold: PayU сообщает об ожидающем платеже (наличные или банк), уплаченная сумма или валюта не соответствует итогу заказа, либо одобрен платёж по отменённому заказу. Причина указана в заметке к заказу: проверьте платёж в модуле PayU, затем обработайте заказ, восстановите его или верните платёж.

Failed: последняя попытка оплаты отклонена, просрочена или завершилась ошибкой. Заметка показывает сообщение PayU. Покупатель может оплатить снова. Отказ по более ранней попытке или по заказу с уже одобренным платежом только добавляется в заметку.

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

Возвраты

Возвраты не выполняются из WooCommerce. Верните транзакцию в модуле PayU и при необходимости вручную зарегистрируйте возврат в WooCommerce.

Лицензионный ключ

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху WooCommerce > Settings > Payments > PayU LATAM. Вставьте ключ в License key и нажмите Activate. Блок показывает статус, например дату окончания действия лицензии и ваш домен. Используйте Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа с сайта. Ссылка Manage licenses and domains in your account открывает вашу учётную запись vibefox.net.

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает место для домена. Освободите его в своей учётной записи vibefox.net.

Без активного ключа PayU LATAM не показывается покупателям при оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Авторизованные управляющие магазином по-прежнему видят способ оплаты с пометкой (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать плагин до покупки ключа. На странице плагинов и страницах WooCommerce появляется напоминание. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются.

После истечения лицензии плагин продолжает работать, но для обновлений и поддержки требуется продление. Статус автоматически проверяется повторно в фоновом режиме.

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

PayU LATAM не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён и заполнены идентификатор мерчанта, идентификатор счёта и ключ API текущей среды: тестовые учётные данные при включённом Sandbox, рабочие — при выключенном. Убедитесь, что валюта магазина (или заказа на странице оплаты заказа) — ARS, BRL, CLP, COP, MXN, PEN или USD. Страница настроек показывает предупреждение для каждой из этих проблем.

Платёж прошёл, но заказ остаётся в статусе Pending payment: подтверждение PayU не дошло до магазина или было отклонено. Убедитесь, что URL подтверждения из настроек доступен из интернета (не локальный сайт, без режима обслуживания, блокировки межсетевым экраном и защиты паролем). Проверьте отклонённые подтверждения в WooCommerce > Status > Logs, источник wcp_payu_latam_payment. PayU повторно отправляет подтверждение после любого ответа с ошибкой.

Подтверждение получает ответ Invalid signature: оно подписано не ключом API среды платежа. Проверьте API Key для рабочих платежей и Sandbox API key для тестовых.

Подтверждение получает ответ Merchant mismatch: идентификатор мерчанта в подтверждении отличается от Merchant ID или Sandbox merchant ID среды платежа. Введите идентификатор мерчанта учётной записи PayU, обрабатывающей платежи.

Подтверждение получает ответ Gateway not configured: отсутствует ключ API или идентификатор мерчанта среды платежа, например тестовые учётные данные удалены во время ожидания тестового платежа. Введите их снова; PayU повторяет подтверждение.

Подтверждение получает ответ Busy, retry later: другой запрос одновременно обновлял заказ. Ничего не изменилось, PayU отправляет подтверждение снова.

Подтверждение получает ответ Unknown reference: платёжная ссылка-идентификатор не принадлежит заказу PayU LATAM этого магазина, например заказ переведён на другой способ оплаты или удалён.

Заказ имеет статус On hold: прочитайте заметку к заказу. Платёж ещё ожидается в PayU (наличные или банк), уплаченная сумма или валюта отличалась от заказа, либо платёж поступил после отмены заказа. Проверьте транзакцию в модуле PayU.

Другие валюты или поля формы: разработчики могут изменить список валют фильтром payu_lp_supported_currencies, значок при оформлении заказа фильтром payu_lp_icon, а поля формы WebCheckout фильтром payu_lp_payment_fields.

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите место в учётной записи vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now для активации ключа на новом домене. Если сервер лицензий недоступен, плагин продолжает работать с последним известным статусом.

Удаление

Отключение плагина сохраняет все данные. Для удаления отключите и удалите его на странице Plugins. Лицензионный ключ и статус лицензии плагина удаляются всегда. Настройки шлюза и журналы плагина удаляются только если был включён Delete data. Иначе они остаются для последующей установки. Существующие заказы сохраняют платёжные заметки, ссылки-идентификаторы PayU и идентификаторы транзакций.

PayU — товарный знак соответствующего владельца. Этот плагин не связан с PayU и не одобрен PayU.