VibeFox Netopia for PrestaShop — Помощь

Требования

PrestaShop: от 8.0 до 9.x.

PHP: 8.0 или новее с расширениями OpenSSL, DOM и SimpleXML. Без них модуль не устанавливается.

Валюта: валюта корзины должна быть RON, EUR, USD или GBP. EUR, USD и GBP должны быть включены в вашей учётной записи Netopia. Для других валют способ оплаты скрыт на этапе оформления заказа.

Учётная запись Netopia: нужна учётная запись продавца Netopia Payments с точкой продаж. В её технических настройках нужны подпись учётной записи и для каждой используемой среды (sandbox и рабочая) открытый сертификат (.cer) и закрытый ключ (.key). На стороне Netopia ничего настраивать не нужно: адрес IPN передаётся с каждым запросом на оплату.

Публичный магазин: URL IPN (подтверждения) должен быть доступен из интернета, а не закрыт логином или базовой аутентификацией. Заказы создаются только по IPN от Netopia.

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

Установка

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

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

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

4. В административной панели Netopia откройте свою точку продаж, скопируйте подпись учётной записи и скачайте сертификат и закрытый ключ для среды sandbox и рабочей среды. Вставьте подпись и полное содержимое файлов в настройки (см. Настройки).

5. Включите Enable/Disable и нажмите Save. Проверьте оплату в тестовом режиме sandbox, затем выключите Test mode, чтобы принимать реальные платежи.

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

Настройки

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

IPN (confirm) URL

Отображается только для чтения вверху страницы. При включённых ЧПУ он выглядит так: https://your-shop/module/wcp_netopia_gateway/notify, возможно, с кодом языка, например /en/. Он передаётся с каждым запросом на оплату как URL подтверждения, поэтому вводить его в административной панели Netopia не нужно. Netopia отправляет IPN на этот адрес. Модуль расшифровывает её закрытым ключом той среды, в которой была начата оплата, и проверяет подпись вашей учётной записи и запрос на оплату. Netopia сообщает о следующих действиях:

Уведомление с кодом ошибки Netopia (например, отклонённая карта) переводит ожидающий заказ в статус Payment error; без заказа покупатель может оплатить снова. Уведомления, которые невозможно расшифровать, которые содержат другую подпись учётной записи или не относятся к запросу на оплату этой корзины, отклоняются и ничего не меняют.

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

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

Title: название способа оплаты, которое показывается на этапе оформления заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: Card Payment (Netopia).

Description: описание способа оплаты, которое показывается на этапе оформления заказа. По умолчанию: Pay securely with your credit or debit card via Netopia.

Учётная запись Netopia

В административной панели Netopia перейдите в Seller accounts > your point of sale > Technical settings: скопируйте подпись учётной записи и скачайте открытый сертификат (.cer) и закрытый ключ (.key) каждой среды. Откройте файлы в текстовом редакторе и вставьте их полное содержимое, включая строки BEGIN/END.

Account signature: подпись учётной записи продавца (формат XXXX-XXXX-XXXX-XXXX-XXXX), одинаковая для sandbox и рабочей среды.

Test mode: использует тестовую среду Netopia (sandboxsecure.mobilpay.ro) и тестовые ключи. По умолчанию: on. Выключите его, чтобы принимать реальные платежи рабочими ключами.

Sandbox public certificate (.cer): содержимое файла открытого сертификата sandbox. Используется для шифрования запроса на оплату.

Sandbox private key (.key): содержимое файла закрытого ключа sandbox. Используется для расшифровки IPN.

Live public certificate (.cer): содержимое файла открытого сертификата рабочей среды.

Live private key (.key): содержимое файла закрытого ключа рабочей среды.

Сохранённые закрытые ключи больше никогда не показываются. Поле остаётся пустым, а его подсказка начинается с A private key is saved. Оставьте поле пустым, чтобы сохранить ключ, или вставьте новый ключ, чтобы заменить его. Пустое поле сертификата удаляет сертификат.

Clear saved private keys: отметьте ключ и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённый ключ.

Заказы

Order status after payment: статус оплаченного заказа.

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

Debug log: записывает запросы и обработку IPN в logs/netopia_p_debug.log.php в папке модуля. Файл нельзя открыть через веб. Данные карт, ключи и данные покупателей не записываются. Ошибки, например отклонённые IPN, записываются всегда, даже когда опция выключена. По умолчанию: off.

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

Delete data on uninstall: при удалении модуля удаляет настройки шлюза, записи платежей Netopia модуля и журнал. Заказы сохраняются. По умолчанию: off.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Card Payment (Netopia)) и подтверждает выбор. Следующая страница показывает Redirecting you to Netopia for secure payment… и автоматически отправляет покупателя на страницу оплаты Netopia; запасными вариантами служат кнопки Proceed to payment и Cancel (возврат к оформлению заказа). Запрос на оплату шифруется вашим сертификатом Netopia и содержит сумму корзины в валюте корзины, Cart # с номером корзины, а также контактные данные для выставления счёта и доставки. В режиме sandbox запрос уходит в тестовую среду Netopia. На этом этапе заказа ещё не существует.

Покупатель оплачивает картой на странице Netopia и возвращается в ваш магазин. Само возвращение никогда не создаёт и не оплачивает заказ. Заказ отмечается оплаченным только после подтверждения Netopia по IPN. Если заказ существует, покупатель видит стандартную страницу подтверждения заказа. Для ожидающего заказа показывается Netopia has not confirmed your payment yet. You will receive an e-mail as soon as the payment is confirmed. Для заказа в статусе On hold показывается Your payment is awaiting confirmation. We will e-mail you as soon as the order is confirmed. Для отменённого заказа показывается The payment was cancelled at Netopia, so this order was cancelled. You can place a new order at any time. Для заказа с ошибкой оплаты показывается The payment was declined by Netopia.

Если IPN ещё не пришла, когда покупатель возвращается, страница Payment confirmation показывает тот же текст «ещё не подтверждено» с кнопками Check again и Back to checkout. Заказ создаётся, как только придёт IPN.

Если Netopia сообщила об отмене или отклонении до создания заказа, покупатель возвращается к оформлению заказа с сообщением The payment was cancelled at Netopia. You can try again or choose another payment method. или The payment was declined by Netopia. You can try again or choose another payment method. Корзина сохраняется. Каждая новая попытка — это новый запрос на оплату; более ранние запросы по этой корзине остаются действительными, поэтому поздняя IPN от предыдущей попытки всё равно будет зарегистрирована.

Если модуль настроен неправильно, покупатель остаётся на этапе оформления заказа с сообщением Netopia gateway is not configured properly. Please contact the store administrator. Другие сообщения: Netopia cannot process payments in с валютой, This order has nothing to pay. и Payment encryption failed. Please try again or contact support. Техническая причина записывается в журнал.

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

Модуль принимает оплату картами только по протоколу карточных платежей Netopia v1. Он не поддерживает возвраты и списания из PrestaShop, сохранённые карты и оплату в один клик, подписки, рассрочку и другие способы оплаты, а также Netopia API v2.

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

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

Заказа пока нет: покупатель был отправлен в Netopia и ещё не оплатил, или Netopia ещё не отправила IPN. Существует только корзина.

Payment accepted or Delivered: Netopia подтвердила платёж. Статус соответствует Order status after payment. Платёж записывается с транзакцией Netopia в качестве ID транзакции, а приватное примечание показывает сумму, замаскированный номер карты и транзакцию Netopia; тестовые платежи sandbox помечаются как [sandbox].

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

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

Payment error: Netopia сообщила об ошибке, например об отклонённой карте, для ожидающего заказа.

Canceled: Netopia отменила платёж ожидающего заказа.

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

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

Блок Netopia

На странице заказа отображается блок Netopia Payments с транзакцией Netopia, средой (sandbox или рабочая), запросом на оплату, последним действием IPN, замаскированной картой, суммами оплаченной, возвращённой и оставшейся, а также историей возвратов. Блок только для чтения.

Возвраты

Возвраты не оформляются из PrestaShop: протокол карточных платежей Netopia v1 не имеет вызова возврата. Оформите возврат транзакции в административной панели Netopia. Затем Netopia отправит IPN о зачислении, и модуль автоматически зарегистрирует возврат в заказе с примечанием Netopia refund processed: и суммой. Частичный возврат сохраняет статус заказа; когда возвращать больше нечего, заказ переходит в статус Refunded. Для заказов в EUR, USD и GBP возвращённая сумма, которую Netopia указывает в RON, пересчитывается обратно в валюту заказа. Возврат никогда не регистрируется дважды и не может превышать оставшуюся сумму. Если Netopia сообщает об ошибке возврата, добавляется только примечание.

Модуль не создаёт кредитные накладные и не возвращает товары на склад. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Netopia.

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

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

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

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

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

Netopia не отображается на этапе оформления заказа: проверьте, что лицензия активна, Enable/Disable включён, активная среда заполнена полностью (Account signature плюс сертификат и закрытый ключ sandbox в тестовом режиме или рабочей среды в рабочем режиме) и валюта корзины — RON, EUR, USD или GBP. Страница настроек показывает предупреждение, если чего-то не хватает. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Оплата прошла, но заказ не создан: IPN не дошла до вашего магазина или была отклонена. Проверьте, что URL IPN (подтверждения) из настроек доступен из интернета (без базовой аутентификации и брандмауэра). Посмотрите поле Log на странице модуля: отклонённые IPN записываются всегда. Включите Debug log, чтобы видеть каждую IPN. Одно лишь возвращение покупателя никогда не создаёт заказ.

В журнале failed decrypting data: закрытый ключ не соответствует сертификату, который использовала Netopia. IPN расшифровывается сохранённым закрытым ключом каждой среды, поэтому сохраняйте ключ другой среды, пока её платежи открыты. Netopia повторит IPN.

В журнале signature mismatch: Account signature отличается от точки продаж, которая отправила IPN. Скопируйте её заново из административной панели Netopia.

В журнале unknown payment request: IPN не соответствует запросу на оплату, который ваш магазин создавал для этой корзины в этой среде (sandbox или рабочей). Ничего не меняется.

В журнале gateway not configured: не сохранён закрытый ключ или подпись учётной записи. Netopia повторит IPN, а платёж будет зарегистрирован, когда настройки будут заполнены.

В журнале busy, retry later or processing failed: корзина в тот же момент обрабатывалась другим запросом, или заказ не удалось создать (например, модуль отключён). Netopia автоматически повторит IPN.

Ошибка при сохранении сертификата или закрытого ключа: вставленный текст не является действительным сертификатом или ключом. Вставьте полное содержимое файла, включая строки BEGIN/END. Предыдущее значение сохранено.

Заказ в статусе Netopia payment on hold после оплаты: прочитайте приватное примечание к заказу (см. Статусы заказа). Сумма или валюта отличались, списана только часть, заказ был отменён или тестовый платёж sandbox был подтверждён, пока магазин работал в рабочем режиме. Проверьте транзакцию в административной панели Netopia.

Возврат, оформленный в Netopia, не появляется в заказе: IPN о зачислении не дошла до магазина или была отклонена. Проверьте журнал.

Удаление

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

Netopia Payments и mobilPay являются товарными знаками их правообладателей. Этот модуль не связан с Netopia Payments и не одобрен ею.