VibeFox Ozow for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

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

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

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

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

Установка

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

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

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

4. Введите Site Code и Private Key, а желательно и API Key, которые берутся в личном кабинете мерчанта Ozow.

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

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

Настройка

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

Ozow

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

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

Description: текст под способом оплаты при оформлении заказа. По умолчанию: 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. (только если описание не пустое).

Учётные данные 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 каждый успешный платёж дополнительно подтверждается через Ozow GetTransaction API, прежде чем заказ будет отмечен оплаченным. API должен сообщить, что платёж завершён, для этой корзины, с той же суммой, валютой и Site Code.

Сохранённые ключи больше не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение только для изменения.

Clear saved secrets: отметьте Private Key или API Key и сохраните, чтобы удалить сохранённый ключ. Пустое поле оставляет сохранённое значение.

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

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

URL уведомления, успеха, отмены и ошибки отправляются в Ozow с каждым платежом, поэтому в личном кабинете Ozow ничего настраивать не нужно, если только ваш сайт Ozow не настроен на фиксированные URL. В разделе показаны все четыре URL: Notification URL, Success URL, Cancel URL и Error URL. Это ссылки модуля вашего магазина (контроллеры notify и return). Если ваш сайт Ozow использует фиксированные URL, скопируйте их точно так, как их показывают настройки.

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

Debug log: записывает запросы на оплату и ответы Ozow в logs/ozow_p_debug.log.php в папке модуля (недоступно из веба). Ошибки и предупреждения записываются всегда. Ключи, хеши, токены и данные покупателей никогда не записываются. По умолчанию: off.

Log: показывает текущий размер и конец журнала, а также кнопку Clear log.

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

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Instant EFT (Ozow)) и подтверждает заказ. Модуль отправляет покупателя на размещённую страницу оплаты Ozow с подписанным запросом на сумму корзины в ZAR. Назначение платежа в выписке: Cart и номер корзины (до 20 латинских букв, цифр, пробелов и дефисов). Имя покупателя передаётся в Ozow. На этом этапе заказа ещё нет. На странице Ozow покупатель выбирает южноафриканский банк и подтверждает платёж в банковском приложении.

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

После успешной оплаты покупатель видит стандартную страницу подтверждения заказа. Если 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. Если Ozow ещё не подтвердил платёж, когда покупатель вернулся, страница показывает текст ожидания и кнопки 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.

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

Модуль принимает только разовые платежи в ZAR. Возвраты из PrestaShop, подписки, сохранённые банковские счета или токенизация, а также отправка платёжных ссылок из бэк-офиса не поддерживаются.

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

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

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

Payment accepted: платёж подтверждён. Сообщение заказа показывает сумму, идентификатор транзакции Ozow и то, подтвердил ли платёж GetTransaction API. Идентификатор транзакции платежа заказа — это TransactionId Ozow. Тестовый платёж получает сообщение TEST MODE — no money was received, do not ship this order.

Awaiting Ozow payment: Ozow или банк проверяет платёж. Заказ обновится, когда Ozow пришлёт окончательный статус.

Ozow payment on hold: сообщение заказа указывает причину: оплаченная сумма или валюта отличаются от корзины; платёж пришёл для уже отменённого заказа; либо, с API Key, GetTransaction API пока не смог подтвердить платёж или противоречит ему. Проверьте платёж в личном кабинете Ozow и измените статус заказа. Если API не ответил, следующее уведомление Ozow завершит заказ.

Ошибка оплаты: платёж, находившийся на проверке, был отменён, брошен или не прошёл. Более позднее успешное сообщение Ozow по нему всё равно отмечает заказ оплаченным.

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

Блок оплаты Ozow

На странице заказа показан блок Ozow payment со ссылкой на транзакцию и попыткой, идентификатором транзакции Ozow, статусом, запрошенной суммой, суммой, указанной Ozow, сообщением Ozow и отметкой TEST MODE для тестовых платежей.

Возвраты

Возвраты из PrestaShop не поддерживаются. Верните платёж в личном кабинете мерчанта Ozow, затем вручную зафиксируйте возврат в PrestaShop.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Ozow Pay — первый блок на странице Modules > Module Manager > VibeFox Ozow Pay > Configure, над настройками. Вставьте ключ в License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действительна, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-ozow и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку back office (включены английский и русский).

Если ключ не принят, блок сообщает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

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

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

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

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

Ozow не появляется при оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включено, что заполнены Site Code и Private Key и что валюта корзины — ZAR. В Payment > Preferences проверьте, что модулю разрешены ZAR, страна покупателя и группа покупателя. Страница настроек показывает предупреждение, если чего-то не хватает.

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

Уведомление отвечает 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 GetTransaction API не смог подтвердить платёж (заказ на удержании, следующее уведомление его завершит; если он остаётся на удержании, проверьте API Key и платёж в личном кабинете Ozow). Этот ответ также приходит, когда возврат покупателя обрабатывался для той же корзины в тот же момент, или когда заказ не удалось создать; см. журнал.

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

Заказ в статусе Ozow payment on hold после оплаты: прочитайте сообщение заказа и проверьте платёж в личном кабинете Ozow, затем установите заказу статус Payment accepted или верните платёж в Ozow.

Удаление

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

Ozow — торговая марка её правообладателя. Этот модуль не связан с Ozow и не одобрен Ozow.