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.