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

Требования

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

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

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

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

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

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

Установка

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

OpenCart 3

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

2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Nexi XPay Gateway и нажмите Install (зелёная кнопка +). Вашему пользователю администратора нужно право на изменение списка платёжных расширений.

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

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

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

OpenCart 4

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

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

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

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

После новой установки способ оплаты выключен, а тестовый режим включён.

Настройка

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

При сохранении поле Title не может быть длиннее 128 символов, Sort Order должен быть целым числом, Total — числом не меньше 0, а гео-зона и статусы заказов должны существовать; если что-либо из этого неверно, ничего не сохраняется. Пробелы вокруг вставленных алиасов и ключей удаляются.

Nexi XPay

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

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

Description: текст, который покупатель видит на шаге Confirm Order. По умолчанию: Pay securely with your credit card via Nexi XPay.

Sort Order: место Nexi XPay среди способов оплаты при оформлении заказа. Оставьте поле пустым или введите целое число.

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

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

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

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

Test Mode: использует тестовую среду Nexi XPay и тестовые учётные данные. Выключите его, чтобы принимать реальные платежи с боевыми учётными данными. По умолчанию: включено. Пока режим включён, покупатели на шаге Confirm Order видят TEST MODE: the payment goes to the Nexi XPay test environment, no real money is charged.

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

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

Боевая среда

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

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

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

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

Оплата

Notification URL: показан для справки. На OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_nexi_gateway/s2s&nexi_order={order_id}, на OpenCart 4 так: https://your-store/index.php?route=extension/wcp_nexi_gateway/payment/wcp_nexi_gateway.s2s&nexi_order={order_id}, в конце стоит номер заказа; формируется из адреса витрины вашей установки OpenCart. Он передаётся в Nexi с каждым платежом, поэтому в back office Nexi ничего настраивать не нужно. Nexi отправляет результат платежа на этот URL от сервера к серверу и также передаёт его вместе с возвратом покупателя. Оба варианта подписаны одинаково и проверяются MAC-ключом среды, в которой был совершён платёж, алиасом этой среды и кодом транзакции, выданным для данного заказа. Результаты, не прошедшие проверку, отклоняются и ничего не меняют.

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

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

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ, missing order). Статус он получает только по проверенному результату Nexi. Каждое поле ниже перечисляет ваши статусы заказов OpenCart. В OpenCart нет статуса On hold: по умолчанию используется Pending, а примечание к заказу объясняет причину. Собственные статусы можно создать в System > Localisation > Order Statuses и выбрать здесь.

Status: Processing: используется, когда Order Status After Payment равен Processing. По умолчанию: Processing.

Status: Completed: используется, когда Order Status After Payment равен Completed. По умолчанию: Complete.

Status: awaiting payment: Nexi сообщает о платеже как об ожидающем (esito PEN). По умолчанию: Pending.

Status: on hold: несовпадение суммы или валюты, платёж, полученный за отменённый заказ, отложенное списание (авторизовано, но ещё не списано) или Order Status After Payment, установленный в On hold. По умолчанию: Pending.

Status: payment failed: ожидающий платёж, который затем не прошёл. По умолчанию: Failed.

Status of cancelled orders: статус, который ваш магазин использует для отменённых заказов. Платёж, полученный за такой заказ, переводится в удержание, но никогда не отмечается как оплаченный. Расширение только читает этот статус и никогда его не устанавливает. По умолчанию: Canceled.

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Credit Card (Nexi)). На OpenCart 4 покупатель выбирает его кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления. На шаге Confirm Order покупатель видит ваше описание. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, страница показывает Redirecting to the Nexi XPay payment page... и Please do not close this window. и через секунду автоматически отправляет покупателя на страницу Nexi XPay, а в качестве запасного варианта есть кнопка Pay with Nexi XPay. Платёж отправляется в EUR на сумму заказа с новым кодом транзакции, e-mail покупателя и описанием Order, номером заказа и названием вашего магазина. Страница Nexi открывается на языке магазина покупателя, если это итальянский, английский, испанский, французский, немецкий, японский, китайский, арабский, русский или португальский; в противном случае — на английском.

Покупатель оплачивает и возвращается в ваш магазин. Заказ отмечается оплаченным только после проверенного результата Nexi с точной суммой и валютой заказа: из уведомления от сервера к серверу или из подписанного возврата покупателя — что придёт первым. Затем заказ получает статус стандартным для OpenCart способом, с обычным письмом о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart с сообщением 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. Для заказа на удержании (отложенное списание или ручная проверка) показывается Your Nexi XPay payment has been received and is being reviewed. We will contact you if anything is needed.

Если к моменту возврата покупателя результат ещё не обработан, страница Payment confirmation показывает 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. На OpenCart 4 эти сообщения показываются над страницей оформления заказа. Заказ без статуса остаётся без статуса, корзина сохраняется, и покупатель может оплатить снова. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, OpenCart 4 оставляет один заказ на оформление и оплачивает тот же заказ снова с новым кодом транзакции. Если другой заказ из той же корзины уже оплачен, ожидает оплаты или находится на удержании, покупатель переходит на страницу успешного оформления вместо нового платежа.

OpenCart 4 хранит заказ на странице оформления до показа страницы успешного оформления. Если этот заказ был закрыт без оплаты в это время (например, ожидающий платёж не прошёл или вы его отменили), покупатель возвращается к оформлению с сообщением Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., в том числе когда он возвращается с Nexi, а следующее нажатие Confirm Order оплачивает новый заказ. Если заказ был оплачен, а затем закрыт магазином (например, возвращён), сообщение: Your previous order #(number) was closed by the store. Please confirm the order again to pay with a new order. Если заказ оформления уже размещён, а корзина с тех пор изменилась, сообщение: Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. Изменение корзины, включая новое количество, считается новой корзиной, которой нужна собственная оплата.

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

Уведомление работает и тогда, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы платёжных расширений, а на OpenCart 4 расширение добавляет для этого стартовое действие, которое также пропускает возврат покупателя из Nexi.

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

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

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

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

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

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

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

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

Status: payment failed: ожидающий платёж не прошёл.

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

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

Вкладка VibeFox Nexi XPay Gateway

В Sales > Orders откройте заказ, оплаченный через Nexi XPay. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Nexi XPay Gateway показывает код транзакции (codTrans) с меткой Test environment для тестовых платежей, статус и результат Nexi, режим и состояние списания, сумму, отправленную в Nexi, и полученную сумму, код авторизации, марку карты, сообщение Nexi, дату и Nexi XPay notes заказа. Вкладка показывается пользователям, у которых есть доступ к расширению.

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

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

Возвраты

Возвраты из OpenCart не выполняются, поэтому для Nexi XPay кнопки возврата нет. Оформите возврат в back office Nexi XPay, а затем вручную зафиксируйте его в OpenCart. Возвраты товаров в Sales > Returns не возвращают деньги через Nexi.

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

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

Если ключ не принят, блок сообщает причину, например 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. Администратор, вошедший в административную часть в том же браузере, по-прежнему видит способ оплаты в магазине с пометкой (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать расширение до покупки ключа. На OpenCart 4 этот предпросмотр недоступен: магазин не видит вход администратора, поэтому без активного ключа способ оплаты скрыт для всех. После того как вы один раз открыли страницу Edit, на Dashboard администратора появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а авторизованные платежи всё ещё можно списать.

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

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

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

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

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

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

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

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

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

Заказ после оплаты находится в статусе удержания: прочитайте Nexi XPay notes на вкладке заказа. Выбрано отложенное списание (спишите платёж кнопкой), сумма или валюта не совпали, пришёл платёж за отменённый заказ, или Order Status After Payment установлен в On hold.

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

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

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Nexi XPay Gateway. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Orders, которые при повторной установке возвращаются к значениям по умолчанию. Событие OpenCart этого расширения также удаляется (на OpenCart 4 удаляются его события и стартовое действие, которое пропускает уведомление в режиме обслуживания). Если Delete Data on Uninstall включено, удаляются остальные настройки шлюза (название, описание, тестовый режим, алиасы, MAC-ключи, списание, статус заказа после оплаты, журнал отладки) и журнал. Если выключено, они сохраняются для будущей повторной установки. Записи о платежах Nexi XPay по заказам всегда сохраняются, поэтому авторизованные платежи можно списать и после повторной установки. Существующие заказы сохраняют свои примечания об оплате.

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

Nexi и XPay являются товарными знаками их соответствующих владельцев. Это расширение не аффилировано с Nexi и не одобрено ею.