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

Требования

PrestaShop: 8.0–9.x.

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

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

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

Доступ вашего магазина из интернета: PayU отправляет результат оплаты в ваш магазин со своих серверов, поэтому магазин должен быть доступен из интернета (не локальный сайт и не сайт за паролем).

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

Установка

1. В панели администратора перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По окончании загрузки нажмите Configure или позже найдите VibeFox PayU LATAM Payment в списке модулей и нажмите Configure.

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

4. Введите учётные данные тестовой среды и рабочие учётные данные (см. раздел Конфигурация). В PayU настраивать URL подтверждения не нужно.

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

При установке модуль создаёт два статуса заказа: Awaiting PayU LATAM payment и PayU LATAM payment on hold. PrestaShop предлагает новый способ оплаты для всех валют, стран и групп покупателей. Ограничить его можно в разделе Payment > Preferences. Страну, включённую позже, нужно отметить там и для модуля.

Конфигурация

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox PayU LATAM Payment > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает Sandbox mode. Payments go to the PayU sandbox and no real money is charged., пока включена тестовая среда; ошибку, если не заполнены идентификатор мерчанта, идентификатор счёта или ключ API текущей среды; и предупреждение, если PayU LATAM не обрабатывает валюту магазина по умолчанию. Пока учётные данные не заполнены, PayU LATAM не показывается на этапе оформления заказа. Пробелы в начале и в конце учётных данных игнорируются. Страница не сохраняет пустое поле Title и показывает Enter a title for the payment method.

PayU LATAM

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

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: платежи отправляются в тестовую среду PayU с учётными данными тестовой среды, указанными ниже, и реальные деньги не списываются. Когда опция выключена, используются рабочие учётные данные и рабочая платёжная страница PayU. По умолчанию: включено. Пока она включена, покупатели видят под способом оплаты Sandbox mode: no real money is charged.

Рабочие учётные данные

Найти их можно в модуле PayU: Settings > Technical configuration (merchant ID, API key) и Accounts (account ID страны, в которой вы продаёте). В разделе есть ссылка на панель мерчанта 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 больше не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Clear saved secrets: отметьте API Key или Sandbox API key и нажмите Save, чтобы удалить сохранённый ключ. Пустое поле оставляет сохранённое значение.

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

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

Этот раздел показывает URL, на который PayU сообщает о каждом результате оплаты. При включённых понятных URL он выглядит так: https://your-shop/module/wcp_payu_latam_payment/confirmation, возможно с кодом языка, например /en/. Модуль передаёт его в PayU с каждым платежом, поэтому в PayU ничего настраивать не нужно. URL должен быть доступен из интернета. Он работает и когда магазин переведён в режим обслуживания, и не блокируется ограничением по странам магазина. PayU подписывает подтверждение вашим ключом API. Подтверждения без корректной подписи, с другим идентификатором мерчанта или с платёжной ссылкой, которую этот магазин не выдавал, отклоняются. Модуль обрабатывает такие статусы транзакций PayU:

4 (approved): оплата прошла. Заказ создаётся оплаченным, если сумма и валюта совпадают с корзиной.

6 (declined), 5 (expired), 104 (error): оплата не удалась. Заказ не создаётся, корзина сохраняется.

7, 10, 12, 14, 15, 18 (pending): платёж ожидает, например оплата наличными или банковским переводом, которую покупатель ещё не завершил. Заказ создаётся в статусе Awaiting PayU LATAM payment.

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

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

Debug log: записывает запросы на оплату и уведомления PayU в файл logs/payu_lp_debug.log.php в папке модуля. Файл нельзя открыть из браузера. Ключи и персональные данные не записываются. Ошибки и отклонённые уведомления записываются всегда, даже когда этот переключатель выключен. По умолчанию: выключено.

Log: показывает размер журнала и его последние записи. Нажмите Clear log, чтобы очистить журнал.

Delete data: удаляет настройки и журналы при удалении модуля. Данные PayU по заказам (попытки оплаты) и статусы заказов сохраняются. По умолчанию: выключено.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию PayU LATAM) и подтверждает выбор. Страница магазина показывает You are being redirected to PayU LATAM to complete the payment... и автоматически отправляет подписанную форму на страницу PayU WebCheckout. Если этого не произошло, покупатель нажимает Pay with PayU LATAM или Back to checkout, чтобы вернуться. На этом этапе заказа ещё не существует.

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

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

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

После подписанного отказа, истечения срока или ошибки: покупатель возвращается к оформлению заказа с сообщением Your PayU LATAM payment was not approved, причиной от PayU, если она есть, и You can try again or choose another payment method. Корзина сохраняется.

Без транзакции PayU (покупатель покинул страницу PayU): покупатель возвращается к оформлению заказа с сообщением Your PayU LATAM payment was not completed. You can try again or choose another payment method.

Заказ уже существует: покупатель видит стандартную страницу подтверждения заказа. Для заказа в статусе Awaiting PayU LATAM payment она показывает Your PayU LATAM payment is pending (for example, a cash or bank payment that has not been completed yet). We will process the order as soon as PayU confirms the payment. Для заказа, который находится на удержании, — We have received your PayU LATAM payment and are reviewing it. We will contact you if anything is needed. Для заказа в статусе Payment error — Your PayU LATAM payment was not approved. Please contact us.

PayU ещё не подтвердил платёж: страница показывает We are waiting for PayU LATAM to confirm your payment. You will receive an e-mail as soon as it is confirmed. (или ожидающий текст выше для оплаты наличными или банковским переводом) с кнопкой Check again. Подтверждение создаёт заказ сразу, как только приходит.

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

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

Заказы

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

Заказа пока нет: покупатель отправлен в PayU и не оплатил, платёж был отклонён или PayU ещё не прислал подтверждение. Существует только корзина.

Payment accepted: PayU подтвердил платёж, сумма и валюта совпадают. Платёж записывается с идентификатором транзакции PayU, а примечание показывает транзакцию, сумму, способ оплаты и [sandbox] для платежей в тестовой среде.

Awaiting PayU LATAM payment: PayU сообщает о платеже как об ожидающем (оплата наличными или банковским переводом). Заказ переходит в Payment accepted, когда PayU подтверждает платёж.

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

Payment error: ожидающий платёж последней попытки позже был отклонён, истёк или завершился ошибкой. В примечании показано сообщение PayU. Эту корзину нельзя оплатить снова: покупатель оформляет новый заказ. Отказ по более ранней попытке или по заказу, у которого уже есть одобренный платёж, добавляется только как примечание.

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

Блок оплаты PayU LATAM

На странице заказа показан блок PayU LATAM payment с референсом, идентификатором транзакции, референсом PayU, статусом и состоянием PayU, запрошенной суммой, суммой, которую сообщил PayU, способом оплаты, сообщением PayU, значком SANDBOX для платежей в тестовой среде, списком всех попыток оплаты корзины и PayU LATAM notes заказа.

Возвраты

Возвраты не выполняются из PrestaShop. Сделайте возврат транзакции в модуле PayU, затем вручную зафиксируйте возврат в PrestaShop.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox PayU LATAM Payment — первый блок на странице Modules > Module Manager > VibeFox PayU LATAM Payment > Configure, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-payu-latam и ссылка 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 LATAM не показывается покупателям на этапе оформления заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в back office, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его на этапе оформления заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются подтверждением PayU и возвратом покупателя.

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

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

PayU LATAM не появляется на этапе оформления заказа: проверьте, что лицензия активна, Enable/Disable включено и заполнены идентификатор мерчанта, идентификатор счёта и ключ API текущей среды: учётные данные тестовой среды, когда Sandbox включено, рабочие — когда выключено. Проверьте, что валюта корзины ARS, BRL, CLP, COP, MXN, PEN или USD. В разделе Payment > Preferences проверьте, разрешён ли модуль для валюты корзины, страны покупателя и группы покупателя.

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

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

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

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

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

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

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

Покупатель видит This payment method is not available: модуль не разрешён для страны, валюты или группы покупателя в Payment > Preferences, либо Enable/Disable выключено.

Заказ в статусе PayU LATAM payment on hold: прочитайте примечания в блоке PayU LATAM payment. Оплаченная сумма или валюта отличались от корзины, либо платёж пришёл после отмены заказа. Проверьте транзакцию в модуле PayU.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox PayU LATAM Payment и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete data включено, настройки и журнал удаляются. Если выключено, все настройки сохраняются для повторной установки. Попытки оплаты и статусы заказов Awaiting PayU LATAM payment и PayU LATAM payment on hold сохраняются всегда, поэтому поздно пришедшее подтверждение PayU по старой попытке распознаётся и после повторной установки. Существующие заказы сохраняют свои примечания об оплате, референсы PayU и идентификаторы транзакций.

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