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

Требования

PrestaShop: 8.0–9.x.

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

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

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

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

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

Установка

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

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

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

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

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

При установке модуль создаёт статус заказа Nets payment on hold. PrestaShop привязывает новый модуль оплаты только к странам, которые были активны на момент установки. Проверьте валюты, страны и группы покупателей модуля в разделе Payment > Preferences.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Nets Nexi Gateway > Configure. У каждого раздела есть своя кнопка 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., пока включён тестовый режим.

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

В заголовке раздела показывается TEST или LIVE для выбранного режима.

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

Title: название способа оплаты, которое видит покупатель при оформлении заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: Nets Easy. Обязательно: пустое название даёт ошибку Enter a title for the payment method., и ничего не сохраняется.

Description: описание способа оплаты, которое видит покупатель при оформлении заказа. По умолчанию: Pay securely with Nets Easy.

Ключи API

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

Test Mode: тестовый режим использует test.api.dibspayment.eu с тестовым секретным ключом; рабочий режим использует api.dibspayment.eu с рабочим секретным ключом. Возвраты и списания заказа всегда используют ту среду, в которой он был оплачен. По умолчанию: включено. Пока режим включён, покупатели видят под способом оплаты надпись 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 saved secrets: отметьте ключ и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

Оплата

Webhooks: уведомления Nets (вебхуки) регистрируются автоматически с каждым платежом. В портале Nets ничего настраивать не нужно. Раздел показывает адрес, на который они отправляются. С понятными адресами он выглядит так: https://your-shop/module/wcp_nets_nexi_gateway/webhook, возможно с кодом языка, например /en/. Если адрес не является публичным HTTPS-адресом, раздел предупреждает, что магазин не получает вебхуки; тогда платежи подтверждаются при возврате покупателя в магазин или проверкой Nets: check payment status and capture на странице заказа. Регистрируются следующие события:

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

Order Status After Payment: статус заказа после того, как Nets подтвердил и списал платёж.

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

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

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

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

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Nets Easy) и подтверждает. Модуль создаёт платёж Nets на сумму корзины в валюте корзины, передавая товары, доставку, подарочную упаковку и скидки как позиции заказа, и отправляет покупателя на размещённую страницу оплаты Nets. Номер платежа в Nets — это номер корзины. E-mail, имя, адрес и телефон покупателя передаются в Nets, если Nets принимает их формат. На странице Nets выводится ссылка на страницу условий и положений вашего оформления заказа (если не задана, — на главную страницу магазина). На этом этапе заказ ещё не существует.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Nets: модуль получает платёж из API Nets, сравнивает зарезервированную сумму и валюту с корзиной, списывает резервирование и только после этого создаёт заказ. Это происходит при вебхуке или при возврате покупателя — что случится раньше. Затем покупатель видит стандартную страницу подтверждения заказа. Если платёж пока не удалось подтвердить (Nets был недоступен или в тот момент его подтверждал другой запрос), страница Payment confirmation показывает Your Nets payment is being confirmed. Your order will be created 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. Корзина сохраняется. При новой попытке модуль сначала проверяет предыдущий платёж: если он уже оплачен, создаётся заказ вместо нового платежа. Иначе предыдущая сессия Nets закрывается до начала новой.

Если Nets не может начать оплату, покупатель остаётся на этапе оформления с коротким сообщением, например 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. Подробности записываются в журнал.

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

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

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

No order yet: покупатель был отправлен в Nets и не оплатил, или платёж ещё не подтверждён. Существует только корзина.

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

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

Canceled: резервирование заказа в статусе ожидания было отменено, например в портале Nets.

Refunded: платёж полностью возвращён через модуль.

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

Блок оплаты Nets Easy

На странице заказа показывается блок Nets Easy payment с ID платежа, ID списания, средой (с отметкой Test environment для тестовых платежей), статусом, суммами, зарезервированными и списанными в Nets, суммой заказа и возвращённой суммой, историей возвратов и Nets notes заказа. Кнопки блока работают для всех сотрудников, которые могут редактировать заказы; доступ к страницам модулей не нужен.

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

Возвраты

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

Модуль не создаёт кредит-ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Nets. Возвраты, сделанные в портале Nets, не синхронизируются; при необходимости обновите заказ вручную.

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

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

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

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

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

Nets Nexi не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён и в выбранном режиме есть секретный ключ: Test Secret Key в тестовом режиме, Live Secret Key в рабочем. На странице настроек появляется предупреждение, если ключ отсутствует. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Оплата прошла, но заказ не создан: вебхук не дошёл до вашего магазина. Проверьте, что магазин использует HTTPS и понятные адреса, так что адрес в Webhooks — публичный HTTPS-адрес без «&», и что секретный ключ среды платежа задан. Заказ также создаётся, когда покупатель возвращается в магазин после оплаты.

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

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

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

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

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

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

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

Удаление

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

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