VibeFox Netopia for OpenCart — Помощь

Требования

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

PHP: 8.0 или новее, с расширениями OpenSSL, DOM и SimpleXML.

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

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

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

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

Установка

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

OpenCart 3

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

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

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

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

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

OpenCart 4

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

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

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

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

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

Настройка

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

При сохранении Title может содержать до 128 символов, Sort order должен быть целым числом (отрицательные значения допустимы), Minimum total — числом не меньше 0, а геозона и статусы заказов должны существовать; если что-то из этого неверно, ничего не сохраняется. Некорректный сертификат или закрытый ключ отклоняется с ошибкой красным цветом, и предыдущее значение сохраняется, а остальные поля при этом сохраняются (Settings saved, except the values shown in red.). Если способ оплаты включён, но активная среда не заполнена, при сохранении появляется предупреждение.

URL IPN (подтверждения)

В первом разделе в режиме только для чтения показан IPN (confirm) URL. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_netopia_gateway/notify, в OpenCart 4 — так: https://your-store/index.php?route=extension/wcp_netopia_gateway/payment/wcp_netopia_gateway.notify. Он формируется из публичного адреса вашей установки OpenCart. Он передаётся с каждым запросом на оплату как URL подтверждения, поэтому вводить его в административной части Netopia не нужно. Netopia отправляет IPN на этот URL. Расширение расшифровывает её закрытым ключом той среды, в которой был начат платёж, и проверяет подпись вашей учётной записи и запрос на оплату. Netopia сообщает о следующих действиях:

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

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

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

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

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

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

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

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

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

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

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

Test mode: использует песочницу Netopia (sandboxsecure.mobilpay.ro) и ключи песочницы. По умолчанию: включено. Выключите, чтобы принимать настоящие платежи боевыми ключами (secure.mobilpay.ro). Пока режим включён, покупатель на шаге Confirm Order видит Test mode (Netopia sandbox): no real money is charged.

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

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

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

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

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

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Он получает статус, только когда Netopia сообщает о платеже. У OpenCart нет собственных статусов заказов Netopia, поэтому каждое поле ниже перечисляет ваши статусы заказов OpenCart. Примечания к заказу объясняют каждое изменение.

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

Processing status: по умолчанию: В обработке.

Completed status: по умолчанию: Выполнен.

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

Netopia payment on hold: платёж требует вашей проверки (см. Order statuses). По умолчанию: Ожидание, так как в OpenCart нет статуса На удержании. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь. Расширение различает случаи «ожидание» и «на удержании», даже если оба используют один и тот же статус.

Canceled status: Netopia отменил платёж заказа в ожидании. По умолчанию: Отменён.

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

Refunded status: после возвратов, сделанных в административной части Netopia, возвращать больше нечего. По умолчанию: Возвращён.

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

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

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Card Payment (Netopia)). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to the Netopia secure page to pay with your card. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение формирует запрос на оплату, шифрует его сертификатом Netopia активной среды и сразу отправляет покупателя на страницу оплаты Netopia. Запрос содержит сумму заказа в валюте заказа, Order # с номером заказа, а также контактные данные для выставления счёта и доставки с телефоном заказа. В режиме песочницы запрос уходит в песочницу Netopia. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа.

Покупатель оплачивает картой на странице Netopia и возвращается в ваш магазин. Сам возврат никогда не оплачивает заказ. Заказ помечается оплаченным только после подтверждения Netopia через IPN. Затем заказ получает статус стандартным для OpenCart способом, с обычным письмом о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Для заказа в ожидании страница показывает Netopia has not confirmed your payment yet. You will receive an e-mail as soon as the payment is confirmed. Для заказа на удержании она показывает 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. На OpenCart 4 эти сообщения показываются над страницей оформления заказа. Корзина сохраняется. Каждая новая попытка — это новый запрос на оплату; предыдущие запросы остаются действительными, поэтому позднее IPN по предыдущей попытке тоже будет записано. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, а OpenCart 4 оставляет один заказ для оформления и оплачивает тот же заказ новым запросом на оплату. Если другой заказ из той же корзины уже оплачен, находится в ожидании или на удержании, покупатель переходит на страницу успеха и новый платёж не запускается.

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

Если платёж не удаётся начать, покупатель остаётся на шаге Confirm Order с сообщением над кнопкой: 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 работает и тогда, когда магазин находится в режиме обслуживания, потому что OpenCart 3 пропускает запросы расширений оплаты, а в OpenCart 4 расширение добавляет для этого стартовое действие (startup action), которое также пропускает возврат покупателя из Netopia.

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

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

Order statuses

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

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

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

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

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

Canceled status: Netopia отменил платёж заказа в ожидании.

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

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

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

Вкладка VibeFox Netopia Gateway

В Sales > Orders откройте заказ, оплаченный через Netopia. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Netopia Gateway показывает блок Netopia Payments: транзакцию Netopia, среду (песочница или боевая), запрос на оплату, статус запроса, последнее действие IPN, замаскированную карту, суммы оплаченного, возвращённого и оставшегося, историю возвратов и Netopia notes заказа. Вкладка доступна только для чтения и показывается пользователям, которые имеют доступ к расширению.

Возвраты

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

Возвраты товаров в Sales > Returns не возвращают деньги через Netopia.

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

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

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

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

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

Netopia does not appear at checkout: проверьте, что лицензия активна, Enable/Disable включено, активная среда заполнена (Account signature плюс сертификат и закрытый ключ песочницы в тестовом режиме или боевой среды в боевом режиме), и что покупатель оформляет заказ в RON, EUR, USD или GBP. Страница настроек показывает предупреждение, если чего-то не хватает. Также проверьте, что платёжный адрес входит в выбранную Geo zone, и что сумма заказа достигает Minimum total.

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

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

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

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

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

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

Error on save about the certificate or private key: вставленный текст не является корректным сертификатом или ключом. Вставьте полное содержимое файла, включая строки BEGIN/END. Предыдущее значение сохранено.

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

Order is in the on-hold status after payment: прочитайте примечания во вкладке VibeFox Netopia Gateway (см. Order statuses). Сумма или валюта отличались, списана только часть, заказ был отменён, или тестовый платёж песочницы был подтверждён, пока магазин работает в боевом режиме. Проверьте транзакцию в административной части Netopia.

A refund made in Netopia does not appear on the order: кредитовое IPN не дошло до магазина или было отклонено. Проверьте журнал.

Для разработчиков: список принимаемых валют можно изменить с помощью события OpenCart netopia_p_supported_currencies.

Удаление

Откройте Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Netopia Gateway. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort order, Geo zone, Minimum total и статусы заказов OpenCart в разделе Orders, которые при повторной установке возвращаются к значениям по умолчанию. Событие OpenCart расширения также удаляется (в OpenCart 4 — также его события и стартовое действие, которое пропускает IPN в режиме обслуживания). Если включено Delete data on uninstall, удаляются остальные настройки шлюза (название, описание, подпись учётной записи, тестовый режим, сертификаты, закрытые ключи, статус после оплаты, журналирование) и журнал. Если выключено, они сохраняются для повторной установки. Платёжные записи Netopia всегда сохраняются, поэтому запоздалое IPN по платежу, начатому до переустановки, всё равно найдёт свой заказ. Существующие заказы сохраняют свои примечания об оплате.

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

Netopia Payments и mobilPay — торговые марки их владельцев. Это расширение не связано с Netopia Payments и не одобрено им.