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

Требования

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

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

Учётная запись Nets: нужны секретные ключи вашей учётной записи Nets Easy (тестовый и боевой). Используются только секретные ключи. Ключи checkout не нужны, так как покупатели платят на размещённой странице оплаты Nets.

Валюты и способы оплаты: расширение само не ограничивает валюты. Используйте валюты, включённые в вашей учётной записи Nets; неподдерживаемую валюту Nets сообщит при создании платежа. Какие способы оплаты увидит покупатель, зависит от вашего договора с Nets, страны и валюты.

HTTPS для вебхуков: Nets обращается только к публичным HTTPS-адресам длиной не более 256 символов и без «&», поэтому для приёма вебхуков магазину нужен HTTPS. Без него платёж всё равно подтверждается, когда покупатель возвращается в магазин, или при проверке статуса на странице заказа.

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

Установка

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

OpenCart 3

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

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

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

4. Скопируйте тестовый секретный ключ с тестового портала Nets Easy и вставьте его в поле Test Secret Key (см. Настройка). В портале Nets ничего настраивать не нужно.

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

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Nets Nexi Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если отсутствует секретный ключ выбранного режима, например Nets Nexi: enter the Test Secret Key — the payment method is hidden at checkout until the key of the selected mode is set., а пока включён тестовый режим показывает Nets Nexi is in test mode: payments go to the Nets test environment and no real money is charged. Без права на изменение расширения страница показывает настройки, но не может их сохранить.

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

Nets Nexi (страны Северной Европы)

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

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

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

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

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

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

Ключи API

Скопируйте секретные ключи из портала Nets Easy в разделе Company > Integration: тестовый портал (test.portal.dibspayment.eu) для тестового ключа и боевой портал (portal.dibspayment.eu) для боевого ключа. В разделе есть ссылки на оба портала. Ключи checkout не нужны.

Test Mode: тестовый режим использует test.api.dibspayment.eu с тестовым секретным ключом; боевой режим использует api.dibspayment.eu с боевым секретным ключом. Возвраты и списания по заказу всегда выполняются в той среде, где заказ был оплачен. По умолчанию: включено. Пока режим включён, покупатели на шаге Confirm Order видят Test mode: no real money will be charged.

Test Secret Key: ваш секретный ключ API тестовой среды Nets.

Live Secret Key: ваш секретный ключ API боевой среды Nets.

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

Оплата

Webhooks: уведомления Nets (вебхуки) регистрируются автоматически с каждым платежом. В портале Nets ничего настраивать не нужно. В поле показан адрес, на который они отправляются. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_nets_nexi_gateway/webhook, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_nets_nexi_gateway/payment/wcp_nets_nexi_gateway.webhook. Адрес формируется из адреса витрины вашей установки OpenCart. Если это не публичный HTTPS-адрес, поле предупреждает, что магазин не принимает вебхуки; тогда платежи подтверждаются, когда покупатель возвращается в магазин, или через Nets: check payment status and capture на странице заказа. Регистрируются следующие события:

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

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ, missing order). Статус он получает только после того, как платёж прочитан из API Nets (вебхук, возврат покупателя или Nets: check payment status and capture на странице заказа), и соответствующее резервирование списано. Каждое поле статуса ниже перечисляет ваши статусы заказов OpenCart.

Order Status After Payment: статус заказа после того, как Nets подтвердил и списал платёж. По умолчанию: Processing. Выберите Complete, чтобы отмечать оплаченные заказы как выполненные.

Nets Payment On Hold Status: сумма или валюта отличаются от заказа, списание не удалось или покупатель оплатил уже после отмены заказа. Ничего не списывается автоматически, а примечание объясняет причину. По умолчанию: Pending, так как в OpenCart нет статуса On hold. Вы можете создать свой статус в System > Localisation > Order Statuses и выбрать его здесь.

Cancelled Status: устанавливается, когда резервирование заказа отменено в портале Nets. По умолчанию: Canceled.

Refunded Status: устанавливается после полного возврата платежа со страницы заказа. По умолчанию: Refunded.

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Nets Easy). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to the Nets payment page to pay securely. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт платёж Nets на сумму заказа в валюте заказа, передаёт товары, доставку и другие итоги заказа (купоны, ваучеры, сборы) как строки заказа и отправляет покупателя на размещённую страницу оплаты Nets. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Ссылка на платёж в Nets — номер заказа OpenCart. E-mail, имя, адрес доставки и телефон покупателя передаются в Nets, если Nets принимает их формат. На странице Nets указана ссылка на страницу условий оформления заказа вашего магазина (если не задана — на главную страницу магазина).

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Nets: расширение читает платёж из API Nets, сравнивает зарезервированную сумму и валюту с заказом, списывает резервирование и только затем устанавливает статус заказа. Это происходит по вебхуку или при возврате покупателя — что случится первым. После этого заказ получает статус стандартным для OpenCart способом, с обычным письмом о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Если платёж пока не удалось подтвердить (Nets был недоступен или в этот момент его подтверждал другой запрос), страница Payment confirmation показывает Your Nets payment is being confirmed. Your order will be updated as soon as it is confirmed — please do not pay again. с кнопками Check again и Back to checkout.

Если покупатель отменяет платёж на странице Nets, он возвращается к оформлению заказа с сообщением The Nets payment was cancelled. You can try again or choose another payment method. Если ничего не оплачено, выводится The payment was not completed. You can try again or choose another payment method. В OpenCart 4 эти сообщения выводятся над страницей оформления заказа. Корзина сохраняется. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, а OpenCart 4 оставляет один заказ на время оформления и оплачивает тот же заказ заново новым платежом Nets. При повторной попытке расширение сначала проверяет предыдущие платежи корзины; если один из них уже оплачен, подтверждается этот заказ вместо нового платежа. В противном случае предыдущие сессии Nets закрываются, прежде чем начнётся новая. Если другой заказ из той же корзины уже оплачен или находится на удержании, покупатель переходит на страницу успешного оформления.

OpenCart 4 держит заказ на этапе оформления до показа страницы успешного оформления. Если этот заказ был закрыт без оплаты (например, вы отменили его, в том числе после отмены резервирования в портале Nets), покупателя возвращают к оформлению с сообщением Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., в том числе когда покупатель возвращается из Nets, и следующее нажатие Confirm Order оплачивает новый заказ. Заказ этой корзины, который был оплачен, а затем отменён или возвращён, больше не удерживает корзину.

Если Nets не может начать платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением, например Nets could not start the payment with the details of this order. Please check your address and phone number, or choose another payment method., This payment method is temporarily unavailable. Please choose another payment method. или The payment service could not be reached. Please try again in a moment. Сумма заказа, равная нулю, даёт The order total must be greater than zero to pay with Nets. Подробности записываются в журнал.

Вебхук работает и тогда, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы платёжных расширений, а в OpenCart 4 расширение добавляет стартовое действие (startup action), которое также позволяет покупателю вернуться из Nets.

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

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

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

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

Order Status After Payment (default Processing): Nets подтвердил и списал платёж. В примечании указаны ID платежа, ID списания и способ оплаты.

Nets Payment On Hold Status (default Pending): сумма или валюта в Nets отличаются от заказа (не списано), списание было отклонено, или покупатель оплатил после отмены заказа (зарезервировано, не списано). Примечание объясняет причину. Ничего не списывается автоматически. После проверки заказа выполните списание через Nets: check payment status and capture или отмените резервирование в портале Nets.

Cancelled Status (default Canceled): резервирование заказа отменено, например в портале Nets.

Refunded Status (default Refunded): платёж полностью возвращён через расширение.

Когда вебхук или возврат покупателя переводит заказ из статуса удержания в статус оплаты или отменяет его, OpenCart уведомляет покупателя. Повторные вебхуки и перезагрузки страницы никогда не списывают деньги дважды и не добавляют повторных примечаний; оплаченный заказ никогда не изменяется событиями Nets. Если старая ссылка на оплату завершается для заказа, который уже оплачен, или для другого заказа из той же корзины, второе резервирование автоматически освобождается; если оно уже было списано, примечание просит вас вернуть деньги в портале Nets. Если заказ отмечен оплаченным другим способом, зарезервированный платёж Nets не списывается, и об этом есть примечание.

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

Вкладка VibeFox Nets Nexi Gateway

В Sales > Orders откройте заказ, оплаченный через Nets. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Nets Nexi Gateway показывает блок Nets Easy payment: ID платежа, ID списания, среду (с меткой Test environment для тестовых платежей), статус и способ оплаты, суммы, зарезервированные и списанные в Nets, сумму заказа и возвращённую сумму, форму возврата, историю возвратов и Nets notes заказа. Вкладка показывается пользователям, у которых есть доступ к расширению; её кнопки требуют права на изменение расширения (задаётся в System > Users > User Groups).

Nets: check payment status and capture: показывается для заказов, которые ещё не оплачены. Кнопка читает платёж из Nets и списывает резервирование, которое соответствует заказу, в том числе после неудачного списания или после проверки заказа на удержании. Если ничего не изменилось, примечание объясняет причину, например что покупатель ещё не завершил оплату. Статус, установленный этой кнопкой, как и статус, установленный возвратом, меняется напрямую, как ручная смена статуса, без писем и движения товаров на складе.

Возвраты

На вкладке введите Amount (подставляется сумма, которая ещё не возвращена), при необходимости Reason (optional), и нажмите Refund via Nets. Подтвердите вопрос Refund this amount through Nets? This cannot be undone. Полные и частичные возвраты возможны после списания платежа, в пределах суммы заказа; платёж, который только зарезервирован, можно отменить в портале Nets. Возврат идёт на списание заказа в той среде, где платёж был оплачен, поэтому секретный ключ этой среды должен быть задан. Если Nets не принимает возврат, вкладка показывает ошибку и возврат не записывается. Успешный возврат добавляется в историю возвратов и примечания с ID возврата Nets. Полный возврат устанавливает заказу Refunded Status; частичный возврат статус не меняет.

Возвраты товаров в Sales > Returns не возвращают деньги через Nets. Возвраты, сделанные в портале Nets, не синхронизируются; при необходимости обновите заказ вручную.

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

Расширение работает с лицензионным ключом VibeFox, полученным на vibefox.net. Блок лицензии License — VibeFox Nets Nexi Gateway — первый блок на странице Extensions > Extensions > Payments > VibeFox Nets Nexi Gateway > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой лицензия действует, и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-payment-nets-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.

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

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

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

Nets Nexi не отображается при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и в выбранном режиме есть секретный ключ: Test Secret Key в тестовом режиме, Live Secret Key в боевом. Страница настроек показывает предупреждение, если ключа нет. Также проверьте, что адрес оплаты входит в выбранную Geo Zone и что заказ достигает Total, указанного в настройках.

Платёж прошёл, но заказ остаётся без статуса: вебхук не дошёл до вашего магазина. Проверьте, что магазин работает по HTTPS, чтобы адрес в Webhooks был публичным HTTPS-адресом, и что задан секретный ключ среды, в которой прошёл платёж. Заказ также получит статус, когда покупатель вернётся в магазин после оплаты, или при нажатии Nets: check payment status and capture на вкладке заказа.

Вебхук отвечает Unauthorized: вебхук не содержал секрет этого платежа. Вебхуки принимаются только с секретом, зарегистрированным вместе с платежом.

Вебхук отвечает Unknown payment: платёж создан не этим магазином.

Вебхук отвечает Busy, retry later, Payment lookup failed или Payment not reserved yet: другой запрос подтверждал ту же корзину, API Nets был недоступен или резервирование ещё не было видно. Nets повторит вебхук автоматически.

Вебхук отвечает Order could not be updated, retry later: не удалось установить статус заказа. Nets повторит вебхук. Включите Debug log, чтобы увидеть причину.

Адрес вебхука в браузере показывает Method not allowed: это нормально. Адрес принимает только запросы от Nets.

Покупатель видит ошибку после Confirm Order: включите Debug log и посмотрите поле Log на странице расширения. This payment method is temporarily unavailable. Please choose another payment method. обычно означает неверный или отсутствующий секретный ключ. Отклонённую валюту Nets сообщает в журнале. This payment method is not available. означает, что сессия оформления больше не соответствует заказу или способ оплаты тем временем был выключен: покупателю нужно перезагрузить страницу оформления.

Покупатель видит We could not match this payment to an order: ссылка возврата неполная или относится к другому заказу. Если с покупателя списали деньги, найдите платёж в портале Nets и проверьте заказ.

Заказ после оплаты находится в статусе удержания: прочитайте Nets notes на вкладке. Если списание отклонено, повторите его через Nets: check payment status and capture или спишите платёж в портале Nets. Если сумма или валюта не совпадают, проверьте платёж в портале Nets. Если покупатель оплатил после отмены, проверьте заказ и спишите или отмените резервирование.

Refund via Nets отсутствует или не работает: возвраты возможны только после списания платежа; тогда вкладка показывает ID списания. Возврат использует секретный ключ той среды, в которой был оплачен заказ, поэтому этот ключ должен быть задан; иначе вкладка сообщит, какого ключа среды не хватает.

Для разработчиков: перед созданием платежа расширение вызывает событие OpenCart nng_create_payment_payload с телом запроса и заказом; nng_currency_decimals меняет количество знаков после запятой для валюты.

Удаление

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

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

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