VibeFox Nexi XPay for WooCommerce — Помощь

Требования

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

WooCommerce: 7.0 или новее, установлен и активен.

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

Валюта: валюта магазина или заказа должна быть EUR. Для других валют способ оплаты скрывается на странице оформления заказа.

Учётная запись Nexi XPay: нужна учётная запись мерчанта Nexi XPay (интеграция по перенаправлению «Pagamento Semplice») с алиасом (ID терминала) и MAC-ключом вашего терминала. Тестовые и боевые данные разделены: тестовые берутся в тестовой зоне Nexi XPay или на портале разработчиков (developer.nexi.it), боевые — в бэк-офисе Nexi XPay после активации учётной записи мерчанта. В бэк-офисе Nexi ничего настраивать не нужно: адрес уведомления передаётся с каждым платежом.

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

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

Установка

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

2. Нажмите Activate.

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

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

5. Оставьте Test Mode включённым и введите тестовый алиас и MAC-ключ (см. Настройка).

6. Включите Enable/Disable и оформите тестовый заказ. Когда всё работает, введите боевой алиас и MAC-ключ и снимите отметку с Test Mode.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Nexi XPay. Над полями страница показывает Тестовый режим включён: платежи идут в тестовую среду Nexi XPay, реальные деньги не списываются., пока тестовый режим включён, и предупреждает, если шлюз включён, но алиас или MAC-ключ текущего режима пусты, либо если валюта магазина не EUR. В обоих случаях способ оплаты скрывается на странице оформления заказа. Пробелы и переносы строк вокруг вставленных ключей удаляются при сохранении.

Общие

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

Title: название способа оплаты, которое видит покупатель на странице оформления заказа. По умолчанию: Credit Card (Nexi). В тестовом режиме на странице оформления заказа к названию добавляется (TEST MODE).

Description: описание способа оплаты, которое видит покупатель на странице оформления заказа. По умолчанию: Pay securely with your credit card via Nexi XPay.

Тестовая среда

Тестовые платежи идут на int-ecommerce.nexi.it и никогда не списывают деньги с реальных карт. Тестовый алиас и MAC-ключ можно получить в тестовой зоне Nexi XPay или на портале разработчиков (developer.nexi.it).

Test Mode: Enable test mode использует тестовую среду Nexi XPay и тестовые данные. Снимите отметку, чтобы принимать реальные платежи с боевыми данными. По умолчанию: включено.

Test Alias: алиас (ID терминала) вашего тестового терминала Nexi XPay.

Test MAC Key: ключ вычисления MAC вашего тестового терминала Nexi XPay.

Боевая среда

Боевые алиас и MAC-ключ отображаются в вашем бэк-офисе Nexi XPay (ecommerce.nexi.it) после активации учётной записи мерчанта.

Live Alias: алиас (ID терминала) вашего боевого терминала Nexi XPay.

Live MAC Key: ключ вычисления MAC вашего боевого терминала Nexi XPay.

Оплата

URL уведомления передаётся в Nexi с каждым платежом, поэтому в бэк-офисе ничего настраивать не нужно. Раздел показывает этот адрес; он выглядит так: https://your-site/wp-json/wc-nexi-gateway/v1/s2s/{order_id}, в конце которого стоит ID заказа. Nexi отправляет результат платежа на этот URL от сервера к серверу и также передаёт его вместе с возвратом покупателя. Оба подписываются одинаково и проверяются MAC-ключом среды, в которой был совершён платёж, алиасом этой среды и кодом транзакции, выданным для данного заказа. Результаты, не прошедшие проверку, отклоняются и ничего не меняют.

Capture: когда деньги списываются.

Order Status After Payment: статус заказа после успешной оплаты. Статус устанавливается сразу, одним изменением статуса и одним письмом.

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

Debug Log: Enable logging записывает события платежей в WooCommerce > Status > Logs, источник wcp_nexi_gateway. MAC-ключи, данные карт и адреса электронной почты не записываются. Ошибки и предупреждения, например неудачная проверка MAC, записываются всегда, даже при выключенной опции. По умолчанию: выключено.

Delete Data on Uninstall: Remove all plugin settings and logs when uninstalled. По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию Credit Card (Nexi)) и оформляет заказ. Следующая страница показывает Переход на Nexi XPay для оплаты... и автоматически отправляет покупателя на страницу Nexi XPay, с кнопкой Pay Now на случай, если переход не произошёл. Платёж отправляется в EUR с новым кодом транзакции, адресом электронной почты покупателя и описанием Order, номером заказа и названием вашего сайта. Страница Nexi открывается на языке магазина, если это итальянский, английский, испанский, французский, немецкий, японский, китайский, арабский, русский или португальский; в остальных случаях — на английском.

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

Если платёж отклонён или покупатель отменил оплату на странице Nexi, он возвращается на оформление заказа (или на страницу Pay for order, если корзина пуста) и видит одно из сообщений: Платёж не был завершён. Повторите попытку или выберите другой способ оплаты., Платёж отменён. Повторите попытку. или Не удалось подтвердить платёж. Если с вашей карты списаны деньги, свяжитесь с нами, прежде чем платить повторно. Отмена на странице Nexi оставляет заказ без изменений, поэтому покупатель может оплатить снова.

Если плагин не настроен для текущего режима, покупатель видит Этот способ оплаты сейчас недоступен. Выберите другой способ оплаты.

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

Плагин принимает платежи только на странице Nexi XPay. В нём нет возвратов из WooCommerce, сохранённых карт или OneClick, подписок и регулярных платежей, Pay-By-Link, встроенных полей XPay Build и способов оплаты, выбранных в WooCommerce: страница Nexi показывает способы, включённые на вашем терминале.

Заказы и возвраты

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

Ожидает оплаты: покупатель был отправлен в Nexi и ещё не оплатил или отменил оплату на странице Nexi.

В обработке, Выполнен или На удержании: Nexi подтвердил платёж. Статус соответствует Order Status After Payment. В примечании к заказу указаны код авторизации, код транзакции, марка карты и сообщение Nexi. ID транзакции — это код транзакции Nexi.

На удержании (авторизован): выбрано отложенное списание, и платёж только авторизован. Спишите его действием заказа Capture Nexi XPay payment.

На удержании (в ожидании): Nexi сообщил, что платёж ожидает подтверждения. Заказ обновится по окончательному результату.

На удержании после оплаты: сумма или валюта, полученные от Nexi, не совпали с заказом (заказ не отмечен оплаченным), либо пришёл успешный платёж для уже отменённого заказа. Примечание к заказу объясняет причину. Проверьте платёж в бэк-офисе Nexi XPay и обработайте или верните средства по заказу.

Не удался: последняя попытка оплаты была отклонена, отменена или завершилась ошибкой. Покупатель может оплатить снова.

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

Отложенное списание

Для авторизованного заказа на удержании откройте заказ, выберите Capture Nexi XPay payment в действиях заказа и нажмите стрелку. Плагин спишет авторизованную сумму в среде платежа и отметит заказ оплаченным со статусом из Order Status After Payment. Если списание не удалось, ошибка выводится на экран заказа и добавляется в примечания, а заказ остаётся на удержании.

Возвраты

Возвраты из WooCommerce не выполняются, поэтому кнопки Refund via нет. Выполните возврат в бэк-офисе Nexi XPay, а затем зафиксируйте его вручную в WooCommerce.

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

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

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

Без активного ключа Nexi XPay не показывается покупателям на оформлении заказа. Если платёж всё же начат, покупатель видит Этот способ оплаты недоступен. Выберите другой. Авторизованные администраторы магазина по-прежнему видят способ оплаты, помеченный как (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а отложенные платежи можно списать.

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

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

Nexi XPay не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, в текущем режиме заполнены обе учётные данные (Test Alias и Test MAC Key в тестовом режиме, Live Alias и Live MAC Key в боевом режиме) и валюта магазина или заказа — EUR. В этих случаях на странице настроек выводится предупреждение.

Платёж прошёл, но заказ остаётся в статусе Ожидает оплаты: ни уведомление, ни возврат покупателя не были приняты. Проверьте, что магазин доступен из интернета, что MAC-ключ и алиас соответствуют среде (тестовой или боевой) платежа, и включите Debug Log, чтобы увидеть, что отправил Nexi, в WooCommerce > Status > Logs, источник wcp_nexi_gateway.

Уведомление отвечает invalid_mac или invalid_alias: MAC-ключ или алиас в настройках не совпадают с терминалом, который отправил результат. Скопируйте их заново из тестовой зоны или бэк-офиса Nexi.

Уведомление отвечает unknown_transaction: код транзакции не был выдан этим магазином для данного заказа. Результат игнорируется.

Уведомление отвечает not_configured или busy: алиас или MAC-ключ среды платежа пуст, либо в этот момент другой запрос обновлял заказ. Nexi повторит уведомление.

Заказ на удержании после оплаты: прочитайте примечание к заказу. Выбрано отложенное списание (спишите платёж действием заказа), сумма или валюта не совпали, платёж для отменённого заказа, платёж ожидает подтверждения в Nexi или в качестве статуса после оплаты выбрано На удержании.

Capture Nexi XPay payment отсутствует или не работает: действие показывается только для заказов Nexi, находящихся на удержании как авторизованные с отложенным списанием. Если оно не работает, прочитайте ошибку в примечаниях к заказу; списание использует ключи среды, в которой был совершён платёж.

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

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина всегда удаляются. Настройки шлюза и журналы удаляются только если была включена опция Delete Data on Uninstall. Иначе они сохраняются для повторной установки. Существующие заказы сохраняют свои примечания об оплате и ID транзакций.

Nexi и XPay являются товарными знаками их владельцев. Этот плагин не связан с Nexi и не одобрен компанией Nexi.