VibeFox Tranzila for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта магазину: ILS, USD, EUR або GBP. Для інших валют кошика спосіб оплати приховується на кроці оформлення замовлення.

Термінал Tranzila: потрібна назва терміналу. Пароль терміналу (TranzilaPW) потрібен для handshake і для повернень коштів зі сторінки замовлення. Деякі термінали також вимагають окремий кредитний пароль (CreditPass) для повернень. Назву терміналу та паролі надає Tranzila: їх можна знайти в налаштуваннях вашого терміналу або запитати в службі підтримки Tranzila. Публічної пісочниці Tranzila не має. Для тестування Tranzila надає окремий тестовий термінал; введіть його назву як назву терміналу.

Реальна IP-адреса відвідувача: повідомлення про платежі перевіряються за IP-адресою сервера Tranzila. Якщо ваш магазин розміщено за проксі або CDN, таким як Cloudflare, веб-сервер має передавати PHP реальну IP-адресу відвідувача (REMOTE_ADDR).

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

Встановлення

1. У back office перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox Tranzila Payment Gateway у списку модулів і натисніть Configure.

3. Введіть ліцензійний ключ VibeFox у полі License key у блоці ліцензії вгорі сторінки Configure і натисніть Activate (див. Ліцензійний ключ).

4. Введіть Terminal name (supplier) та Terminal password (TranzilaPW), якщо використовуєте handshake або повернення коштів.

5. Залиште Notifications увімкненим і перевірте Trusted IP: там мають бути перелічені IP-адреси, з яких Tranzila надсилає повідомлення. Підтвердьте список у службі підтримки Tranzila.

6. Рекомендовано: увімкніть handshake у терміналі Tranzila, дозвольте там IP-адресу вашого сервера, а потім увімкніть Handshake у модулі.

7. Увімкніть Enable/Disable, натисніть Save і протестуйте платіж тестовим терміналом Tranzila.

Під час встановлення модуль створює статус замовлення Tranzila payment on hold. PrestaShop пропонує новому платіжному модулю всі валюти, країни та групи клієнтів. Їх можна обмежити в Payment > Preferences.

Налаштування

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Tranzila Payment Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, коли назва терміналу порожня (тоді спосіб оплати приховано на кроці оформлення замовлення), коли повідомлення вимкнені або Trusted IP порожній (оплачені замовлення тоді переходять в очікування ручної перевірки), коли handshake увімкнено без пароля терміналу (сторінку оплати не можна відкрити) і коли валюта магазину за замовчуванням не підтримується. Під час збереження недійсна назва терміналу, недійсний запис у Trusted IP або числове поле, яке не є цілим числом, не зберігаються: сторінка показує помилку, і залишається попереднє значення. Число поза допустимим діапазоном зберігається як найближче допустиме значення, і сторінка повідомляє про це.

Tranzila

Enable/Disable: Enable Tranzila Payment Gateway вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

Title: назва способу оплати, яку бачать клієнти на кроці оформлення замовлення, та заголовок сторінки оплати. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Credit Card (Tranzila).

Description: текст, що відображається під способом оплати на кроці оформлення замовлення. За замовчуванням: Pay securely with your credit card on the Tranzila payment page.

Terminal

Terminal name (supplier): назва вашого терміналу Tranzila, наприклад myshop. Лише літери, цифри, «-» та «_». Доки її не введено, спосіб оплати не показується на кроці оформлення замовлення. Для тестування введіть назву вашого тестового терміналу Tranzila.

Terminal password (TranzilaPW): API-пароль терміналу. Потрібен для handshake і для повернень коштів зі сторінки замовлення.

Refund password (CreditPass): лише якщо ваш термінал вимагає окремий пароль для кредитних операцій (повернень). Інакше залиште порожнім.

Збережені паролі більше ніколи не показуються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Clear saved passwords: позначте пароль і натисніть Save, щоб його видалити. Порожнє поле зберігає збережене значення.

Сторінка оплати

Payment page version: сторінка Tranzila, що відображається у фреймі.

Payment page language: мова сторінки Tranzila: Site language, іврит, англійська, російська, іспанська, німецька, французька або японська. За замовчуванням: іврит. Site language використовує мову кошика покупця, якщо вона входить до цього списку, інакше англійську.

iFrame width (px): від 300 до 1200. За замовчуванням: 600. На малих екранах фрейм ніколи не ширший за сторінку.

iFrame height (px): від 400 до 1500. За замовчуванням: 650.

Max installments: максимальна кількість платежів у розстрочку (tashlumim), яку покупець може обрати на сторінці оплати, до 36. 0 або 1 означає без розстрочки. За замовчуванням: 0. Термінал має бути дозволений для обробки розстрочки.

Handshake: фіксує суму за допомогою токена handshake (рекомендовано). Перед відкриттям сторінки оплати магазин запитує в Tranzila одноразовий токен, прив'язаний до суми, тож суму не можна змінити в браузері. Потрібні пароль терміналу, увімкнений handshake у терміналі Tranzila та дозволена там IP-адреса вашого сервера. За замовчуванням: вимкнено.

Підтвердження оплати

Повідомлення Tranzila не підписуються. Замовлення створюється як оплачене лише тоді, коли повідомлення надійшло з Trusted IP і його токен сторінки оплати, кошик, термінал, сума та валюта збігаються зі сторінкою оплати. З handshake токен також має збігатися зі сторінкою оплати. Повернення покупця зі сторінки оплати ніколи не позначає замовлення оплаченим.

Notifications: автоматично підтверджує платежі за повідомленнями Tranzila (notify URL). За замовчуванням: увімкнено. Коли повідомлення вимкнені, покупець, який повернувся з успішної сторінки оплати, створює замовлення в статусі Tranzila payment on hold, а ви підтверджуєте платіж вручну після перевірки терміналу Tranzila.

Notification URL: показується для інформації. З дружніми URL він має вигляд https://your-shop/module/wcp_tranzila_payment_gateway/notify, можливо, з кодом мови. URL надсилається в Tranzila з кожним платежем, тож вводити його в термінал Tranzila не потрібно.

Trusted IP: IP-адреси або діапазони CIDR серверів Tranzila, які надсилають повідомлення, через коми. За замовчуванням: 80.244.170.7. Актуальний список уточнюйте в службі підтримки Tranzila. Повідомлення з інших адрес відхиляються. Якщо поле порожнє, повідомлення неможливо перевірити: повідомлений про успішну оплату платіж створює замовлення в статусі Tranzila payment on hold для ручної перевірки, а повідомлена відмова нічого не змінює.

Додатково

Debug log: записує події сторінки оплати, повідомлень і повернень у logs/tranzila_p_debug.log.php у папці модуля. Файл не можна відкрити з веб. Попередження та помилки записуються завжди, навіть коли ця опція вимкнена. Паролі, токени та дані покупців ніколи не записуються. За замовчуванням: вимкнено.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб його очистити.

Delete data on uninstall: коли увімкнено, видалення модуля видаляє налаштування та журнали. Транзакції й повернення Tranzila, а також статус замовлення Tranzila payment on hold завжди зберігаються, бо старим замовленням вони потрібні. За замовчуванням: вимкнено.

Оформлення замовлення

На кроці оплати покупець обирає спосіб оплати (за замовчуванням Credit Card (Tranzila)) і бачить опис та примітку After you confirm, you will enter your card details on the secure Tranzila payment page. The order is created once Tranzila confirms the payment. Після підтвердження покупець переходить на сторінку оплати вашого магазину. Там відкривається сторінка оплати Tranzila у фреймі (iframe) із сумою кошика у валюті кошика, платіжними даними та коротким списком товарів. На сторінці написано Enter your card details on the secure Tranzila payment page below. If it does not load, click "Proceed to payment". Посилання Choose another payment method розташоване під фреймом. Якщо розстрочку дозволено, покупець обирає кількість платежів на сторінці Tranzila. На цьому етапі замовлення ще не існує.

Після успішної оплати Tranzila повертає покупця, і все вікно переходить далі. Замовлення позначається оплаченим лише після того, як Tranzila підтвердить оплату повідомленням. Якщо повідомлення вже надійшло, покупець бачить стандартну сторінку підтвердження замовлення з текстом Your payment with Tranzila has been received. Якщо замовлення в очікуванні перевірки, сторінка показує Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed. Якщо повідомлення ще не надійшло, відкривається сторінка Payment confirmation з текстом Your payment is being confirmed by Tranzila. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. та кнопкою Check again.

Якщо оплату відхилено або скасовано, покупець повертається до оформлення замовлення з повідомленням The payment was not completed. You have not been charged — please try again or choose another payment method. Коли Tranzila повідомляє код відповіді, додаються причина та код, наприклад, що термін дії картки минув. Кошик зберігається, замовлення не створюється. Щоразу, коли відкривається сторінка оплати, це нова сторінка оплати зі своїм токеном.

Якщо сторінку оплати не вдається відкрити, наприклад, коли handshake не проходить, покупець бачить коротке повідомлення на кшталт Could not connect to Tranzila. Please try again in a moment. і кнопку Choose another payment method. Технічна причина записується в журнал.

Повідомлення працює, поки магазин перебуває в режимі обслуговування, і не блокується обмеженням за країнами вашого магазину. Та сама сторінка оплати використовується з темами Classic і Hummingbird.

Модуль приймає лише разові платежі карткою на сторінці Tranzila. Він не підтримує збережені картки чи токени, підписки, окремі авторизацію та списання (J5), власні кнопки Bit, Apple Pay або Google Pay (те, що пропонує ваша сторінка оплати Tranzila, відображається всередині iframe) та рахунки Tranzila.

Замовлення та повернення коштів

Статуси замовлення

No order yet: покупця надіслано на сторінку оплати, і він не оплатив, оплату відхилено або повідомлення Tranzila ще не надійшло. Існує лише кошик.

Payment accepted: оплату підтверджено перевіреним повідомленням. Платіж записується з індексом транзакції Tranzila як ID транзакції, а примітка показує суму, транзакцію, номер авторизації та кількість платежів у розстрочку, якщо вони є.

Tranzila payment on hold: про оплату повідомлено, але її не прийнято автоматично: сума, валюта або токен handshake не збіглися, повідомлення не вдалося перевірити, бо Trusted IP порожній, або повідомлення вимкнені, а покупець повернувся з успішної сторінки оплати. Примітка пояснює причину. Перевірте платіж у терміналі Tranzila і змініть статус вручну.

Refunded: платіж повністю повернуто через модуль.

Якщо надходить платіж для скасованого замовлення, воно знову переходить у статус Payment accepted з приміткою, що перед відправкою слід перевірити залишки на складі. Якщо надходить другий платіж за замовлення, яке вже оплачене або повернене, замовлення не змінюється. Примітка просить перевірити його та повернути дублікат у терміналі Tranzila. Повторні повідомлення про ту саму транзакцію ігноруються.

Блок оплати Tranzila

На сторінці замовлення показано блок Tranzila payment з індексом транзакції, номером авторизації, терміналом, статусом, сплаченою та поверненою сумою, кількістю платежів у розстрочку, історією повернень, усіма Payment pages of the cart з їх результатом і Tranzila notes замовлення.

Повернення коштів

У блоці Tranzila payment введіть суму (підставляється сума, яка ще не повернута), за бажанням причину, і натисніть Refund via Tranzila. Підтвердьте запитання Refund this amount via Tranzila? This cannot be undone. Підтримуються повні та часткові повернення. Вам потрібне право редагувати замовлення; доступ до сторінок модулів не потрібен. Повернення виконується як кредитна операція Tranzila для початкового платежу, на тому терміналі, який його прийняв, на суму та у валюті, які Tranzila фактично списала. Тож після розбіжності суми чи валюти можна повернути не більше того, що покупець реально сплатив, а не суму замовлення.

Форма доступна, коли встановлено пароль терміналу і в замовлення є підтверджена транзакція Tranzila з номером авторизації. Інакше блок пояснює причину, наприклад Refunds need the terminal password (TranzilaPW) in the gateway settings. Замовлення, оплачене через інший термінал, ніж той, що зараз вказано в налаштуваннях (наприклад, тестовий), не можна повернути зі сторінки замовлення; поверніть його в цьому терміналі Tranzila.

Якщо Tranzila не приймає повернення, блок показує помилку, наприклад Tranzila declined the refund з кодом і його значенням, і повернення не записується. Успішне повернення додається до історії повернень і приміток з кредитною операцією Tranzila. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює.

Модуль не створює кредитні ноти (credit slips). Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через Tranzila. Повернення, зроблені в терміналі Tranzila, магазину не повідомляються. За потреби оновіть замовлення вручну.

Ліцензійний ключ

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

Без активного ключа Tranzila не показується покупцям на кроці оформлення замовлення. Якщо платіж все одно розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви увійшли в back office, тому спосіб оплати приховано і для вас: налаштувати модуль можна до купівлі ключа, але протестувати його на кроці оформлення замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Існуючі замовлення не зачіпаються: платежі, які вже розпочато, як і раніше підтверджуються сповіщенням Tranzila і поверненням до магазину, а повернення працюють.

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

Усунення несправностей

Tranzila не з'являється на кроці оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, Terminal name (supplier) заповнено і валюта кошика — ILS, USD, EUR або GBP. Сторінка налаштувань показує попередження, коли назва терміналу відсутня або валюта за замовчуванням не підтримується. В Payment > Preferences перевірте, що модуль дозволений для валюти кошика, країни покупця та групи покупця.

Оплата пройшла, але замовлення не створено: повідомлення не надійшло або було відхилено. Перевірте, що Notifications увімкнено і що в Trusted IP вказано адреси, з яких Tranzila надсилає повідомлення. Помилки завжди записуються в журнал; перегляньте поле Log на сторінці модуля. Повідомлення про те, що IP-адреси немає в списку Trusted IP, означає, що потрібно виправити налаштування Trusted IP або конфігурацію проксі: за проксі чи CDN веб-сервер має передавати PHP реальну IP-адресу відвідувача. Розробники, чий магазин розміщено за довіреним зворотним проксі, можуть задати IP за допомогою хука actionTranzilaPRemoteIp.

Повідомлення відповідає Forbidden: воно надійшло з IP-адреси, якої немає в Trusted IP.

Повідомлення відповідає Bad request або Not found: кошик, токен сторінки оплати, термінал або індекс транзакції в повідомленні не відповідають жодній сторінці оплати цього магазину.

Повідомлення відповідає Accepted for manual review: Trusted IP порожній, тож повідомлення не вдалося перевірити. Успішний платіж створює замовлення в очікуванні. Заповніть Trusted IP, щоб платежі підтверджувались автоматично.

Повідомлення відповідає Busy, retry: кошик у той самий момент оброблявся іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). Причину показано в журналі. Перевірте платіж у терміналі Tranzila; якщо там він схвалений, а замовлення не створено, зв'яжіться з покупцем або створіть замовлення вручну.

Деякі замовлення мають статус Tranzila payment on hold: прочитайте примітки в блоці Tranzila payment. Сума, валюта або токен handshake не збіглися, або повідомлення не вдалося перевірити (Trusted IP порожній або повідомлення вимкнені). Перевірте платіж у терміналі Tranzila і змініть статус вручну.

Сторінка оплати не відкривається з увімкненим handshake: перевірте назву терміналу та пароль терміналу, що handshake увімкнено в терміналі Tranzila і що IP-адреса вашого сервера там дозволена. Журнал показує причину.

Повернення не виконуються: для повернень потрібен Terminal password (TranzilaPW). Деякі термінали також вимагають окремий кредитний пароль; введіть його в Refund password (CreditPass). Замовлення, оплачені через інший термінал, слід повертати в цьому терміналі. Якщо відповідь Tranzila несподівана, блок повідомляє, що повернення не підтверджено: перевірте термінал Tranzila, перш ніж повторювати спробу.

Інші валюти: модуль підтримує лише ILS, USD, EUR та GBP.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Tranzila Payment Gateway і виберіть Uninstall. Ключ ліцензії та статус ліцензії цього модуля завжди видаляються. Якщо Delete data on uninstall увімкнено, налаштування та журнали видаляються. Якщо вимкнено, усі налаштування зберігаються для подальшого повторного встановлення. Транзакції й повернення Tranzila, а також статус замовлення Tranzila payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату та ID транзакцій.

Tranzila є торговельною маркою її власника. Цей модуль не пов'язаний з Tranzila і не схвалений нею.