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

Требования

PrestaShop: 8.0–9.x.

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

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

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

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

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

Установка

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

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Nexi XPay Gateway в списке модулей и нажмите Configure.

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

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

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

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

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает Test mode is on: payments go to the Nexi XPay test environment, no real money is charged. пока включён тестовый режим. Она предупреждает, если шлюз включён, но алиас или MAC-ключ текущего режима пусты, или если основная валюта магазина не EUR. В этих случаях способ оплаты скрывается при оформлении заказа. Пробелы и переносы строк вокруг вставленных значений удаляются при сохранении.

Nexi XPay

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

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: использует тестовую среду Nexi XPay и тестовые данные. Выключите его, чтобы принимать реальные платежи боевыми данными. По умолчанию: on.

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.

Сохранённые MAC-ключи больше никогда не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Удаление сохранённых секретов: отметьте Test MAC Key или Live MAC Key и нажмите Save, чтобы удалить сохранённый ключ. Пустое поле сохраняет сохранённое значение.

Платёж

Notification URL: показан для справки. Он передаётся в Nexi с каждым платежом, поэтому в бэк-офисе Nexi ничего настраивать не нужно. С понятными URL он выглядит так: https://your-shop/module/wcp_nexi_gateway/s2s?id_cart={id_cart}, возможно с кодом языка, например /it/, а в конце — номер корзины. Nexi отправляет результат платежа на этот URL от сервера к серверу и также передаёт его вместе с возвратом покупателя. Оба варианта подписываются одинаково и проверяются MAC-ключом среды, в которой был совершён платёж, алиасом этой среды и кодом транзакции, выданным для этой корзины. Результаты, не прошедшие проверку, отклоняются и ничего не меняют.

Capture: момент списания денег.

Order Status After Payment: статус заказа после успешной оплаты.

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

Debug Log: записывает события платежей в logs/nexi_ip_debug.log.php в папке модуля. Открыть файл через веб нельзя. Ключи MAC, MAC-значения, данные карт и адреса электронной почты не записываются. Ошибки и предупреждения, например неудачная проверка MAC, записываются всегда, даже если опция выключена. По умолчанию: off.

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

Delete Data on Uninstall: если включено, при удалении модуля удаляются все его настройки и журнал. Данные платежей Nexi XPay в заказах и статусы заказов сохраняются. По умолчанию: off.

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

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

Покупатель платит и возвращается в ваш магазин. Заказ отмечается как оплаченный только после проверенного результата Nexi с точной суммой и валютой корзины: из серверного уведомления или из подписанного возврата покупателя, что придёт первым. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением Your Nexi XPay payment has been received. Если Nexi сообщает, что платёж в ожидании, страница показывает Your payment is pending confirmation from Nexi XPay. We will update your order as soon as the payment is confirmed. Для заказа на удержании (отложенное списание или ручная проверка) она показывает We have received your Nexi XPay payment authorization. Your order will be processed shortly. Если ожидающий платёж позже не проходит, страница показывает The payment was not completed. Please contact us.

Если на момент возврата покупателя результат ещё не обработан, открывается страница с сообщением We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. и кнопкой Check again. Уведомление создаёт заказ сразу, как только приходит.

Если платёж отклонён или покупатель отменяет оплату на странице Nexi, он возвращается к оформлению заказа и видит одно из сообщений: The payment was not completed. Please try again or choose a different payment method., Payment was cancelled. Please try again. или We could not confirm the payment. If your card was charged, please contact us before paying again. Заказ не создаётся, корзина сохраняется, и покупатель может оплатить снова. Если у корзины уже есть заказ (например, оплата прошла в другой вкладке), покупатель попадает на подтверждение заказа вместо новой оплаты.

Если модуль не настроен для текущего режима, покупатель видит This payment method is not available right now. Please choose another payment method.

Уведомление работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

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

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

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

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

Payment accepted, Delivered or Nexi XPay payment on hold: Nexi подтвердил платёж. Статус следует за Order Status After Payment. Платёж записывается с кодом транзакции Nexi в качестве ID транзакции, а примечание показывает код авторизации, код транзакции, марку карты и сообщение Nexi.

Nexi XPay payment on hold (authorized): выбрано отложенное списание, платёж только авторизован. Спишите его кнопкой Capture Nexi XPay payment на странице заказа.

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

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

Ошибка оплаты: ожидающий платёж не прошёл. Ту же корзину нельзя оплатить снова, поэтому покупателю нужно оформить новый заказ.

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

Блок оплаты Nexi XPay

На странице заказа показан блок Nexi XPay payment с кодом транзакции (codTrans), статусом и результатом Nexi, режимом списания, суммой, отправленной в Nexi, и полученной суммой, кодом авторизации, маркой карты, сообщением Nexi и датой, плашкой Test environment для тестовых платежей и Nexi XPay notes заказа.

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

Для авторизованного заказа на удержании нажмите в блоке Capture Nexi XPay payment (на кнопке указана сумма) и подтвердите вопрос Capture the authorized amount through Nexi XPay? Вам нужно право редактировать заказы. Модуль списывает авторизованную сумму в среде платежа, ключами этой среды, фиксирует платёж и устанавливает статус по Order Status After Payment. Если списание не удалось, блок показывает ошибку, в заказ добавляется примечание, а заказ остаётся на удержании. Повторное списание того же платежа отклоняется.

Возвраты

Возвраты не делаются из PrestaShop, поэтому кнопки возврата для Nexi XPay нет. Сделайте возврат в бэк-офисе Nexi XPay, а затем вручную зафиксируйте его в PrestaShop. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Nexi.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Nexi XPay Gateway — первый блок на странице Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-nexi и ссылка Manage licenses and domains in your account, которая открывает вашу учётную запись vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока соответствуют языку панели администратора (включены английский и русский).

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

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

Без активного ключа Nexi XPay не показывается покупателям при оформлении заказа. Если оплата всё же начата, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в бэк-офис, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать его при оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а авторизованные платежи можно списать.

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

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

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

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

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

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

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

URL уведомления в браузере показывает method_not_allowed: это нормально. URL принимает запросы только от Nexi.

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

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

Тестовые платежи не подтверждают боевой платёж: каждый платёж проверяется ключами среды, в которой он был начат. Переключите Test Mode в нужный режим и используйте алиас и MAC-ключ этого режима.

Удаление

Откройте Modules > Module Manager, раскройте меню рядом с VibeFox Nexi XPay Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete Data on Uninstall включён, настройки модуля и журнал удаляются. Если выключен, все настройки сохраняются для последующей переустановки. Данные платежей Nexi XPay в заказах и статусы заказов Awaiting Nexi XPay payment и Nexi XPay payment on hold всегда сохраняются, поэтому авторизованные платежи можно списать и после переустановки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

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