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 и не одобрен ею.