VibeFox Ozow for OpenCart — Помощь

Требования

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

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

Валюта: южноафриканский рэнд (ZAR). В магазине должна быть валюта ZAR (System > Localisation > Currencies), а способ оплаты отображается только тогда, когда покупатель оформляет заказ в ZAR. Ozow списывает целые центы, поэтому у валюты должно быть 2 знака после запятой.

Учётная запись Ozow: учётная запись мерчанта Ozow с Site Code и Private Key вашего сайта Ozow, которые берутся в панели мерчанта Ozow. API Key необязателен, но рекомендуется. Ozow использует одни и те же Site Code и ключи для тестовых и реальных платежей.

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

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

Установка

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

OpenCart 3

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

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

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

4. Введите Site Code и Private Key, а желательно и API Key, из панели мерчанта Ozow. URL уведомления и возврата передаются в Ozow при каждом платеже, поэтому в панели Ozow ничего настраивать не нужно.

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

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Ozow Pay > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если отсутствует Site Code или Private Key (тогда Ozow скрыт при оформлении заказа), если валюта магазина по умолчанию не ZAR, если у валюты больше 2 знаков после запятой (установите 2 в System > Localisation > Currencies), и показывает Test mode is on: no real payments are accepted. Do not ship orders paid in test mode., пока включён тестовый режим. Без права изменять расширение страница показывает настройки, но сохранить их не может.

Поля Ozow никогда не мешают сохранению, кроме Title длиннее 128 символов (The title must be no longer than 128 characters.). Поля OpenCart проверяются: Sort Order должно быть целым числом (отрицательные числа допускаются), Total — числом не меньше 0, а географическая зона и статусы заказов должны существовать. Если какое-то значение неверно, ошибка называет поле, и ничего не сохраняется.

Ozow

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

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

Description: текст, который видит покупатель на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay instantly and securely from your South African bank account. You will be redirected to Ozow to choose your bank and approve the payment. В тестовом режиме под ним добавляется строка TEST MODE: no money will be charged. (только если описание не пустое).

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

Geo Zone: предлагать Ozow только для платёжных адресов в выбранной географической зоне. По умолчанию: All zones. Географические зоны настраиваются в System > Localisation > Geo Zones. В OpenCart 4, если магазин не запрашивает платёжный адрес, используется адрес доставки.

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

Учётные данные Ozow

Скопируйте Site Code, Private Key и API Key из панели мерчанта Ozow (Merchant details / Sites). В разделе приведена ссылка на документацию по интеграции Ozow на hub.ozow.com.

Site Code: Site Code сайта Ozow, который получает платежи. Ответы для другого Site Code отклоняются.

Private Key: подписывает каждый запрос на платёж и проверяет каждый ответ Ozow. Храните его в тайне. Он сохраняется ровно в том виде, в каком введён. Без него способ оплаты скрывается, и ни один ответ Ozow не принимается.

API Key (recommended): необязательно. С API Key каждый успешный платёж дополнительно подтверждается через API GetTransaction в Ozow, прежде чем заказ будет отмечен как оплаченный. API должен сообщить, что платёж завершён, с той же суммой, валютой и Site Code.

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

Test mode: Ozow использует для тестов те же Site Code и ключи: платежи создаются с IsTest=true, и деньги не движутся. Заказы, оплаченные в тестовом режиме, получают примечание; не отправляйте их. Отключите тестовый режим, чтобы принимать реальные платежи. Тестовый платёж никогда не оплачивает заказ в боевом режиме. По умолчанию: включено.

Уведомления о платежах

В разделе показаны четыре URL, которые расширение отправляет в Ozow с каждым платежом: Notification URL (туда Ozow отправляет уведомление о платеже), Success URL, Cancel URL и Error URL (туда Ozow возвращает покупателя). Они выглядят так: https://your-store/index.php?route=extension/payment/wcp_ozow_pay/notify и https://your-store/index.php?route=extension/payment/wcp_ozow_pay/back&ozow_return=success, в OpenCart 4 — https://your-store/index.php?route=extension/wcp_ozow_pay/payment/wcp_ozow_pay.notify и https://your-store/index.php?route=extension/wcp_ozow_pay/payment/wcp_ozow_pay.back&ozow_return=success. Они формируются из адреса витрины вашей установки OpenCart. В панели Ozow ничего настраивать не нужно. Если на вашем сайте Ozow заданы фиксированные URL, скопируйте их точно так, как они показаны в настройках.

Заказы

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

Order Status After Payment: Ozow сообщил, что платёж Complete с ожидаемыми суммой и валютой (подтверждено через GetTransaction, если задан API Key). По умолчанию: В обработке.

Awaiting Ozow Payment Status: Ozow или банк проверяет платёж (статус Ozow PendingInvestigation). Когда Ozow сообщает Complete, заказ получает статус после оплаты. По умолчанию: Ожидание.

On Hold (Review) Status: платёж требует вашей проверки (см. раздел «Статусы заказов»). Заказ не отмечается как оплаченный. По умолчанию: Ожидание, потому что в OpenCart нет статуса On hold. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Failed Payment Status: платёж, находившийся на проверке, который Ozow затем сообщил как Cancelled, Error или Abandoned. По умолчанию: Неудачный.

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

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

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

Debug log: записывает запросы платежей и ответы Ozow в файл ozow_p_debug.log.php в папке логов OpenCart (storage/logs). Файл нельзя открыть через веб, а при достижении 5 МБ он переименовывается в ozow_p_debug.old.log.php. Ошибки и предупреждения записываются всегда. Ключи, хэши, токены и данные покупателей никогда не записываются. По умолчанию: выключено.

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Instant EFT (Ozow)). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to Ozow to choose your bank and approve the payment. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Когда покупатель нажимает Confirm Order, расширение отправляет его на размещённую страницу оплаты Ozow с подписанным запросом на сумму заказа в ZAR. Ссылка в выписке банка — Order и номер заказа (до 20 латинских букв, цифр, пробелов и дефисов). Имя покупателя передаётся в Ozow. На странице Ozow покупатель выбирает южноафриканский банк и подтверждает платёж в банковском приложении.

Затем Ozow уведомляет магазин и возвращает покупателя. Оба сообщения содержат один и тот же подписанный ответ и обрабатываются одинаково, поэтому заказ получит статус, даже если одно из них потеряется. Заказ отмечается как оплаченный только после подтверждения Ozow: хэш должен проверяться вашим Private Key, Site Code должен быть вашим, ответ должен относиться к этой попытке оплаты заказа, а сумма и валюта должны совпадать с заказом. С API Key платёж дополнительно проверяется через API GetTransaction. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков.

После успешного платежа покупатель видит страницу успешного оформления заказа OpenCart. Если Ozow или банк ещё проверяет платёж, на странице также написано We are waiting for Ozow to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Если заказ находится в статусе проверки, написано Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed. Если проверяемый платёж позже не прошёл или неоплаченный заказ был отменён, написано Your Ozow payment was not completed. Please contact us about this order. (в OpenCart 4 покупатель вместо этого возвращается к оформлению заказа, см. ниже). Если Ozow ещё не подтвердил платёж, когда покупатель возвращается, страница Payment confirmation показывает текст ожидания с кнопками Check again и Back to checkout.

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

OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order. OpenCart 4 хранит один заказ для оформления и обновляет его, поэтому после отменённого или неуспешного платежа покупатель оплачивает тот же заказ новой попыткой. Если другой заказ из той же корзины уже оплачен или ожидает Ozow, покупатель сразу переходит на страницу успеха, а поздний платёж по второму заказу не применяется: примечание к оплаченному заказу просит вас вернуть дубликат через панель Ozow.

Если заказ из корзины был оплачен, а затем отменён или возвращён вами, покупатель возвращается к оформлению заказа и оплачивает корзину новым заказом. В OpenCart 3 появляется сообщение This order was cancelled or refunded by the store. Please confirm the order again to pay with a new order.

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

Если оформление заказа не в ZAR, покупатель видит Ozow accepts payments in South African rand (ZAR) only. Please choose another payment method.

Расширение принимает только разовые платежи в ZAR. Оно не поддерживает возвраты из OpenCart, подписки, сохранённые банковские счета или токенизацию, а также отправку платёжных ссылок из административной части.

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

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

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

В OpenCart 4 неоплаченный заказ оформления может получить статус Voided, который OpenCart 4 устанавливает, когда покупатель возвращается на шаг Confirm Order. Расширение считает такой заказ заказом без статуса, и последующий платёж по-прежнему подтверждает его.

Order Status After Payment (default Processing): платёж подтверждён. Примечание показывает сумму, идентификатор транзакции Ozow и то, подтверждён ли платёж через API GetTransaction. Тестовый платёж получает примечание TEST MODE — no money was received, do not ship this order.

Awaiting Ozow Payment Status (default Pending): Ozow или банк проверяет платёж. Заказ обновляется, когда Ozow отправляет окончательный статус: Order Status After Payment при успехе, Failed Payment Status при неудаче.

On Hold (Review) Status (default Pending): примечание объясняет причину: оплаченная сумма или валюта отличается от заказа; платёж поступил по уже отменённому заказу; либо, с API Key, API GetTransaction пока не может подтвердить платёж или противоречит ему. Проверьте платёж в панели Ozow и измените статус заказа. Если API не смог ответить, следующее уведомление Ozow завершит заказ.

Failed Payment Status (default Failed): платёж, который проверялся, был отменён, прерван или не прошёл. Более позднее успешное сообщение Ozow по этому платежу всё равно отмечает заказ как оплаченный.

Оплаченный заказ никогда не возвращается назад, а отменённый или возвращённый заказ никогда не открывается снова. Если для уже оплаченного заказа поступает второй платёж, примечание просит вас вернуть дубликат через панель Ozow. Тестовый платёж никогда не оплачивает заказ, пока расширение работает в боевом режиме; примечание об этом сообщает.

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

Вкладка VibeFox Ozow Pay

В Sales > Orders откройте заказ, оплаченный через Ozow. В нижней части страницы заказа, рядом с History и Additional, вкладка VibeFox Ozow Pay показывает Transaction reference (номер заказа) и попытку, Ozow transaction ID, Status, запрошенную сумму Requested, Amount reported by Ozow, Ozow message, метку TEST MODE для тестовых платежей и Ozow notes заказа. Вкладка показывается пользователям, у которых есть доступ к расширению.

Возвраты

Возвраты из OpenCart не поддерживаются. Верните платёж через панель мерчанта Ozow, а затем зафиксируйте возврат в OpenCart вручную. Возвраты товаров в Sales > Returns не возвращают деньги через Ozow.

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

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

Один ключ работает на одном домене: адрес магазина из настроек OpenCart. Удаление ключа из магазина не освобождает его слот домена. Освободите слот в своём аккаунте на vibefox.net.

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

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

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

Ozow не отображается при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, поля Site Code и Private Key заполнены и покупатель оформляет заказ в ZAR. Также проверьте, что платёжный адрес входит в выбранную Geo Zone и что сумма заказа достигает Total, заданного в настройках. Страница настроек показывает предупреждение, если чего-то не хватает.

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

Уведомление отвечает Invalid hash: Private Key в настройках не принадлежит сайту Ozow, который отправил ответ. Скопируйте его заново из панели мерчанта Ozow. Ничего не меняется.

Уведомление отвечает Unknown site: ответ пришёл с другого сайта Ozow. Проверьте Site Code.

Уведомление отвечает Order mismatch или Order not found: ответ не относится к платежу, начатому в этом магазине. Ничего не меняется.

Уведомление отвечает Gateway not configured: отсутствует Site Code или Private Key. Заполните их; Ozow может повторить попытку.

Уведомление отвечает Payment not confirmed yet: ответ пока не удалось применить. С API Key API GetTransaction не смог подтвердить платёж (заказ находится в статусе проверки, и следующее уведомление завершит его; если он остаётся в этом статусе, проверьте API Key и платёж в панели Ozow). Такой же ответ приходит, если возврат покупателя в тот же момент обрабатывался для той же корзины; см. журнал.

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

Тестовый платёж не оплатил заказ: расширение работает в боевом режиме. Тестовые платежи никогда не оплачивают заказ в боевом режиме; примечание к заказу или журнал это сообщают.

Заказ после оплаты находится в статусе проверки: прочитайте примечания на вкладке VibeFox Ozow Pay и проверьте платёж в панели Ozow, затем установите статус заказа или верните платёж в Ozow.

Удаление

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

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

Ozow — товарный знак его владельца. Это расширение не связано с Ozow и не одобрено Ozow.