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

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

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

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

Учётная запись PayU Latam: вам нужны три значения из вашей коммерческой учётной записи PayU: ID мерчанта, ID аккаунта страны, в которой вы продаёте, и ключ API. Они находятся в панели мерчанта 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. Один ключ работает на одном домене.

Установка

Загружаемый файл — один zip-архив с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. В нём находятся README.txt, пакет для OpenCart 3 wcp_payu_latam_payment-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_payu_latam_payment.ocmod.zip. Устанавливайте только пакет для своей версии OpenCart. Лицензионный ключ один и тот же для обеих версий.

OpenCart 3

1. В административной части откройте Extensions > Installer, нажмите Upload и выберите файл wcp_payu_latam_payment-oc3-(version).ocmod.zip. В расширении нет модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload этого пакета в корневую папку магазина.

2. Откройте Extensions > Extensions и выберите тип Payments. Найдите VibeFox PayU LATAM Payment и нажмите Install (зелёная кнопка «+»). Вашему пользователю администратора нужно право изменять список платёжных расширений.

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

4. Введите тестовые учётные данные песочницы и рабочие учётные данные (см. Настройка). Указывать адрес подтверждения в PayU не нужно.

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

OpenCart 4

1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_payu_latam_payment.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, а переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox PayU LATAM Payment, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и учётные данные PayU так же, как в шагах 3–5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только URL подтверждения (см. URL подтверждения).

Новая установка начинает работу с выключенным способом оплаты и включённой песочницей.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница показывает Sandbox mode. Payments go to the PayU sandbox and no real money is charged., пока песочница включена; ошибку, если не заполнены ID мерчанта, ID аккаунта или ключ API текущей среды (тогда PayU Latam не предлагается на этапе оформления заказа); и предупреждение, если PayU Latam не обрабатывает валюту магазина по умолчанию. Без права изменять расширение страница показывает настройки, но не может их сохранить.

При сохранении поле Title не должно быть пустым и не может быть длиннее 128 символов (страница показывает Enter a title for the payment method (at most 128 characters).), Sort Order должно быть целым числом (отрицательные числа допустимы), Total должно быть числом не меньше 0, а геозона и статусы заказов должны существовать. Иначе ничего не сохраняется. Пробелы в начале и в конце учётных данных игнорируются.

PayU LATAM

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

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

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

Sort Order: положение PayU LATAM среди способов оплаты на этапе оформления заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать PayU LATAM только для платёжных адресов в выбранной геозоне. По умолчанию: All zones. Геозоны настраиваются в разделе System > Localisation > Geo Zones.

Total: сумма заказа в валюте магазина по умолчанию, которую заказ должен достичь, чтобы предлагался PayU LATAM. Оставьте поле пустым, чтобы предлагать PayU LATAM при любой сумме.

Среда

Sandbox: платежи уходят в песочницу PayU с тестовыми учётными данными, и реальные деньги не списываются. Когда опция выключена, используются рабочие учётные данные и рабочая страница оплаты PayU. По умолчанию: включено. Пока она включена, покупатель на шаге Confirm Order видит 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: ID мерчанта для песочницы PayU.

Sandbox account ID: ID аккаунта для песочницы PayU.

Sandbox API key: ключ API для песочницы PayU.

Сохранённые ключи API больше никогда не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённый ключ, отметьте Clear saved secret on save под полем и нажмите Save.

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

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

В этом разделе показан URL, на который PayU сообщает о каждом результате оплаты. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_payu_latam_payment/confirmation, в OpenCart 4 — https://your-store/index.php?route=extension/wcp_payu_latam_payment/payment/wcp_payu_latam_payment.confirmation. Он формируется по адресу витрины вашей установки OpenCart. Расширение передаёт его PayU с каждым платежом, поэтому в PayU ничего настраивать не нужно. URL должен быть доступен из интернета. Он работает и тогда, когда магазин находится в режиме обслуживания (в OpenCart 4 через стартовое действие расширения, которое также пропускает возврат покупателя из PayU). PayU подписывает подтверждение вашим ключом API. Подтверждения без корректной подписи, с другим ID мерчанта или с платёжным номером, который не выдавал этот магазин, отклоняются. Расширение обрабатывает следующие статусы транзакций PayU:

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

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Заказ получает статус только после подписанного подтверждения PayU. Каждое поле ниже показывает статусы заказов вашего OpenCart.

Order Status After Payment: подтверждённый платёж (статус PayU 4) с ожидаемой суммой и валютой. По умолчанию: В обработке.

Awaiting Payment Status: платёж в ожидании (статусы 7, 10, 12, 14, 15, 18, например наличный или банковский платёж, который ещё не завершён). Заказ получает Order Status After Payment, когда PayU подтверждает платёж. По умолчанию: Ожидание.

On Hold (Review) Status: PayU одобрил платёж, но с другой суммой или валютой, чем у заказа, либо для заказа, который был отменён. Примечание показывает подробности; заказ не отмечается оплаченным. По умолчанию: Ожидание, потому что в OpenCart нет статуса On hold. Вы можете создать собственный статус в разделе System > Localisation > Order Statuses и выбрать его здесь.

Failed Payment Status: платёж в ожидании последней попытки, который PayU затем сообщил как отклонённый, просроченный или неудачный. По умолчанию: Неудачный.

Cancelled Order Status: статус, который ваш магазин использует для отменённых заказов. Платёж, одобренный для такого заказа, переводит его в On Hold (Review) Status вместо отметки об оплате. Расширение никогда не устанавливает этот статус. По умолчанию: Отменён.

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

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

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

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

Импорт / экспорт

Export: Download JSON сохраняет настройки в файл JSON. Ключи API не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые ключи API остаются.

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию PayU LATAM). На шаге Confirm Order покупатель видит ваше описание; OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способов оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Когда покупатель нажимает Confirm Order, расширение готовит подписанную платёжную форму, страница показывает You are being redirected to PayU LATAM to complete the payment... и автоматически отправляет форму на страницу PayU WebCheckout. Если этого не происходит, покупатель нажимает Pay with PayU LATAM.

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

Каждое нажатие Confirm Order запускает новую попытку оплаты с собственным номером (OC, номер заказа и отметка времени). В OpenCart 4 новая попытка оплачивает тот же заказ оформления. Прежние попытки запоминаются: если покупатель оплатит во вкладке PayU от прежней попытки, платёж всё равно будет распознан.

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

В OpenCart 4 эти сообщения показываются над страницей оформления заказа.

OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, OpenCart 4 обновляет заказ оформления, но корзина оплачивается только один раз: если другой заказ из той же корзины уже оплачен, ожидает оплаты или находится на проверке, Confirm Order сразу ведёт на страницу успеха. Изменение корзины, в том числе новое количество, считается новой корзиной, которой нужна собственная оплата. Если учётных данных текущей среды нет, покупатель видит PayU LATAM is not available right now. Please choose another payment method.

В OpenCart 4 заказ остаётся в оформлении, пока не будет показана страница успеха. Если этот заказ был закрыт без оплаты (например, его платёж не прошёл или вы его отменили), покупатель возвращается к оформлению заказа с сообщением Your PayU LATAM payment was not approved и причиной от PayU, если она есть. Если заказ был оплачен, а затем закрыт магазином, либо был оплачен за предыдущую корзину, которая с тех пор изменилась, сообщение: Ваш предыдущий заказ уже закрыт. Подтвердите заказ ещё раз: корзина будет оплачена новым заказом. Следующее нажатие Confirm Order оплачивает новый заказ. Закрытый заказ никогда не показывается как оплаченный.

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

Заказы

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

Без статуса (отсутствующий заказ): покупатель был направлен в PayU и не оплатил, платёж был отклонён или PayU ещё не отправил подтверждение. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным в Missing Orders.

Order Status After Payment (default Processing): PayU подтвердил платёж, сумма и валюта совпадают. Примечание показывает транзакцию, сумму, способ оплаты и то, был ли это платёж в песочнице.

Awaiting Payment Status (default Pending): PayU сообщает о платеже как об ожидающем (наличный или банковский платёж). Заказ переходит в Order Status After Payment, когда PayU подтверждает платёж, или в Failed Payment Status, если платёж не прошёл. OpenCart уведомляет покупателя об этих изменениях.

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

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

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

Примечания — это записи в History заказа, которые покупатель не видит.

Вкладка VibeFox PayU LATAM Payment

В Sales > Orders откройте заказ, оплаченный через PayU LATAM. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox PayU LATAM Payment показывает Reference, Transaction ID, PayU reference, Status и статус PayU, Requested-сумму, Amount reported by PayU, Payment method, PayU message, значок SANDBOX для платежей в песочнице, список всех Payment attempts корзины и PayU LATAM notes заказа. Вкладка показывается пользователям, имеющим доступ к расширению.

Возвраты

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

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox PayU LATAM Payment — первый блок на странице Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-payment-payu-latam и ссылка Управление лицензиями и доменами в вашем аккаунте, которая открывает ваш аккаунт vibefox.net. Изменять ключ могут только пользователи-администраторы с правом Modify для расширения. Тексты блока следуют языку административной части (включены английский и русский).

Если ключ не принят, блок показывает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on и дату. После смены адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, расширение продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: адрес магазина из настроек OpenCart. Удаление ключа из магазина не освобождает слот домена. Освободите его в вашем аккаунте vibefox.net.

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

Когда лицензия истекает, расширение продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова, когда вы открываете Dashboard или страницу Edit в административной части: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Задание cron не требуется. При удалении расширения лицензионный ключ и статус лицензии удаляются всегда.

Решение проблем

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

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

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

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

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

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

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

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

Покупатель видит This payment method is not available. Please reload the checkout page.: сеанс оформления заказа больше не соответствует заказу, либо Enable/Disable тем временем выключили. Покупатель должен перезагрузить оформление заказа.

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

Удаление

Откройте Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка «−») рядом с VibeFox PayU LATAM Payment. Лицензионный ключ и статус лицензии этого расширения удаляются всегда. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Orders, которые при повторной установке возвращаются к значениям по умолчанию. Событие OpenCart расширения также удаляется (в OpenCart 4 — его события и стартовое действие, которое пропускает подтверждение и возврат покупателя в режиме обслуживания). Если Delete data включено, удаляются остальные настройки шлюза (название, описание, песочница, учётные данные, переключатель журнала отладки) и журнал. Если выключено, они сохраняются для будущей повторной установки. Записи попыток оплаты всегда сохраняются, поэтому поздно пришедшее подтверждение PayU по старой попытке распознаётся и после повторной установки. Существующие заказы сохраняют свои примечания об оплате.

На OpenCart 4, чтобы удалить также файлы расширения, после удаления перейдите в Extensions > Installer, нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox PayU LATAM Payment в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

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