VibeFox Tranzila for WooCommerce — Помощь

Требования

WordPress: 6.0 или новее.

WooCommerce: 8.0 или новее, установлен и активен. Плагин не активируется без него.

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

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

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

Реальный IP-адрес посетителя: уведомления о платежах проверяются по IP-адресу сервера Tranzila. Если сайт работает за прокси или CDN, например Cloudflare, веб-сервер должен передавать в PHP реальный IP-адрес посетителя (REMOTE_ADDR).

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

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку wcp_tranzila_payment_gateway в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > Tranzila > Manage или нажмите Settings под названием плагина на странице Plugins.

4. Введите лицензионный ключ VibeFox в блоке лицензии в верхней части страницы и нажмите Activate.

5. Укажите Terminal name (supplier) и, если вы используете handshake или возвраты, Terminal password (TranzilaPW).

6. Оставьте Notifications включённым и проверьте Trusted IP: там должны быть IP-адреса, с которых Tranzila отправляет уведомления. Уточните список у службы поддержки Tranzila.

7. Рекомендуется: включите handshake в терминале Tranzila, разрешите там IP-адрес вашего сервера, затем включите Handshake в плагине.

8. Включите Enable/Disable и проверьте оплату на тестовом терминале Tranzila.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Tranzila. Над полями страница предупреждает: если название терминала не заполнено, способ оплаты скрывается при оформлении заказа; если уведомления отключены или Trusted IP пуст, оплаченные заказы переводятся в статус «на удержании» для ручной проверки; если handshake включён без пароля терминала, страница оплаты не открывается; если валюта магазина не поддерживается. При сохранении некорректное название терминала или некорректная запись в Trusted IP не сохраняются: страница показывает ошибку, а прежнее значение остаётся. Числа вне допустимого диапазона автоматически заменяются ближайшим допустимым значением.

General

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 и для возвратов из WooCommerce.

Refund password (CreditPass): заполняйте, только если терминал требует отдельный пароль для кредитных операций (возвратов). В остальных случаях оставьте пустым.

Payment page

Payment page version: страница Tranzila, которая показывается во фрейме.

Payment page language: язык страницы Tranzila: Site language, Hebrew, English, Russian, Spanish, German, French или Japanese. По умолчанию: Hebrew. Site language использует язык локали WordPress посетителя, если он входит в этот список, иначе English.

iFrame width (px): от 300 до 1200. По умолчанию: 600. На маленьких экранах фрейм никогда не шире страницы.

iFrame height (px): от 400 до 1500. По умолчанию: 650.

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

Handshake: Lock the amount with a handshake token (recommended). Перед открытием страницы оплаты магазин запрашивает у Tranzila одноразовый токен, привязанный к сумме заказа, поэтому сумму нельзя изменить в браузере. Для этого нужны пароль терминала, включённый handshake в терминале Tranzila и разрешённый там IP-адрес вашего сервера. По умолчанию: выключено.

Payment confirmation

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

Notifications: Confirm payments automatically with Tranzila notifications (notify URL). По умолчанию: включено. URL уведомлений передаётся в Tranzila с каждым платежом, поэтому вводить его в терминале Tranzila не нужно. Он выглядит так: https://your-site/wc-api/tranzila_p_callback/ и показывается под полем. Если уведомления выключены, покупатель, вернувшийся со страницы успешной оплаты, переводит заказ в статус «на удержании», а вы подтверждаете оплату вручную после проверки в терминале Tranzila.

Trusted IP: IP-адреса или диапазоны CIDR серверов Tranzila, которые отправляют уведомления, через запятую. По умолчанию: 80.244.170.7. Актуальный список уточните у службы поддержки Tranzila. Уведомления с других адресов отклоняются. Если поле пустое, уведомления нельзя проверить: сообщение об успешной оплате переводит заказ в статус «на удержании» для ручной проверки, а сообщение об отказе не меняет заказ.

Advanced

Debug log: Log payment page, notification and refund events записывает события в WooCommerce > Status > Logs, источник wcp_tranzila_payment_gateway. Ошибки записываются всегда, даже если эта опция выключена. Пароли, токены и данные покупателей никогда не записываются. По умолчанию: выключено.

Delete data on uninstall: Delete the settings, logs and Tranzila order data when the plugin is deleted. По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию Credit Card (Tranzila)) и нажимает Continue to payment. Заказ создаётся со статусом Ожидает оплаты, и покупатель переходит на страницу оплаты заказа вашего магазина. Там открывается страница оплаты Tranzila во фрейме с суммой заказа в его валюте, платёжными данными и коротким списком заказанных товаров. На странице написано: 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 is being confirmed by Tranzila. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Если заказ находится на удержании для проверки, отображается: Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed.

Если платёж отклонён или отменён, покупатель возвращается на страницу оплаты заказа с сообщением 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. Техническая причина записывается в журнал.

Способ оплаты работает в классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. На странице Pay for order он предлагается, если валюта заказа поддерживается. Плагин совместим с WooCommerce High-Performance Order Storage (HPOS).

Плагин принимает только разовые платежи картами на странице Tranzila. Он не поддерживает сохранённые карты и токены, подписки, раздельную авторизацию и списание (J5), собственные кнопки Bit, Apple Pay или Google Pay (всё, что предлагает ваша страница оплаты Tranzila, показывается внутри фрейма) и счета Tranzila.

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

Order statuses

Pending payment: покупатель перешёл на страницу оплаты и ещё не оплатил заказ, либо уведомление Tranzila пока не пришло.

Processing or Completed: оплата подтверждена проверенным уведомлением. WooCommerce ставит статус В обработке или Выполнен для заказов, не требующих доставки. В примечании к заказу указаны сумма, транзакция Tranzila и номер авторизации, а также количество платежей по рассрочке, если она есть. ID транзакции — это индекс транзакции Tranzila.

On hold: платёж получен, но не принят автоматически: сумма, валюта или токен handshake не совпали с заказом; уведомление нельзя проверить, потому что Trusted IP пуст; либо уведомления выключены, а покупатель вернулся со страницы успешной оплаты. Причина указана в примечании к заказу. Проверьте платёж в терминале Tranzila и измените статус вручную.

Failed: Tranzila сообщила об отклонённом платеже для ожидающего оплаты заказа. В примечании указаны код ответа и его значение. Уже оплаченный заказ никогда не переводится в статус Failed.

Если платёж поступил по отменённому заказу, заказ открывается снова, и в примечании вам предлагается проверить остатки перед отправкой. Если покупатель на странице Pay for order сменил способ оплаты, но заплатил на ещё открытой странице Tranzila, способ оплаты заказа возвращается к Tranzila. Если второй платёж поступает по заказу, который уже оплачен, выполнен или возвращён, заказ не меняется. Примечание просит проверить его и вернуть дубликат в терминале Tranzila. Повторные уведомления по одной и той же транзакции игнорируются.

Refunds

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Credit Card (Tranzila) (на кнопке отображается название способа оплаты). Поддерживаются полный и частичный возвраты. Возврат выполняется как кредитная операция Tranzila по исходному платежу. Кнопка доступна, если задан пароль терминала и у заказа есть подтверждённая транзакция Tranzila с номером авторизации. Успешный возврат добавляется в примечания к заказу вместе с кредитной операцией Tranzila.

Если Tranzila не принимает возврат, WooCommerce показывает ошибку, например Tranzila declined the refund с кодом, и возврат не регистрируется. Заказ, оплаченный на терминале, отличном от указанного в настройках (например, на тестовом), нельзя вернуть из WooCommerce: оформите возврат в этом терминале Tranzila. Возвраты, сделанные в терминале Tranzila, магазину не передаются. При необходимости создайте ручной возврат в WooCommerce без кнопки Tranzila.

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

Плагин работает с лицензионным ключом VibeFox, полученным на vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > Tranzila. Вставьте ключ в поле License key и нажмите Activate. В блоке отображаются статус, например дата, до которой лицензия действительна, и ваш домен. Кнопка Check now повторно проверяет статус, Change key позволяет ввести другой ключ, а Remove key удаляет ключ с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

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

Без активного ключа Tranzila не показывается покупателям при оформлении заказа. Если оплата всё же начата, покупатель видит This payment method is not available. Please choose another one. Авторизованные администраторы магазина по-прежнему видят способ оплаты с пометкой (unlicensed — visible to admins only), так что вы можете настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты работают.

Когда лицензия истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется в фоновом режиме.

Решение проблем

Tranzila does not appear at checkout: проверьте, что лицензия активна, Enable/Disable включён, поле Terminal name (supplier) заполнено и валюта магазина (на странице Pay for order — валюта заказа) — ILS, USD, EUR или GBP. На странице настроек выводится предупреждение, если название терминала не заполнено или валюта не поддерживается.

The payment went through, but the order stays Pending payment: уведомление не пришло или было отклонено. Проверьте, что Notifications включены и что Trusted IP содержит адреса, с которых Tranzila отправляет уведомления. Ошибки всегда записываются в WooCommerce > Status > Logs, источник wcp_tranzila_payment_gateway. Сообщение о том, что IP-адреса нет в списке Trusted IP, означает, что нужно исправить настройку Trusted IP или конфигурацию прокси: за прокси или CDN веб-сервер должен передавать в PHP реальный IP-адрес посетителя.

Notification answers Forbidden: уведомление пришло с IP-адреса, которого нет в Trusted IP.

Notification answers Bad request or Not found: заказ, его ключ, терминал или индекс транзакции в уведомлении не соответствуют ни одному заказу этого магазина.

Notification answers Accepted for manual review: Trusted IP пуст, поэтому уведомление не удалось проверить. Успешный платёж переводит заказ в статус «на удержании». Заполните Trusted IP, чтобы подтверждать платежи автоматически.

Notification answers Busy, retry: в тот же момент заказ обрабатывался другим запросом, и уведомление не было применено. Проверьте платёж в терминале Tranzila; если заказ всё ещё ждёт оплаты, а платёж там одобрен, измените статус вручную.

Some paid orders are On hold: прочитайте примечание к заказу. Сумма, валюта или токен handshake не совпали, либо уведомление нельзя проверить (Trusted IP пуст или уведомления выключены). Проверьте платёж в терминале Tranzila и измените статус вручную.

The payment page does not open with the handshake on: проверьте название и пароль терминала, включён ли handshake в терминале Tranzila и разрешён ли там IP-адрес вашего сервера. В журнале указана причина.

Refunds fail: для возвратов нужен Terminal password (TranzilaPW). Некоторым терминалам также нужен отдельный кредитный пароль; введите его в поле Refund password (CreditPass). Заказы, оплаченные на другом терминале, нужно возвращать в этом терминале.

Other currencies: плагин поддерживает ILS, USD, EUR и GBP. Разработчики могут изменить этот список с помощью фильтра tranzila_p_currency_map.

The license block shows an error: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите место в аккаунте vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать с последним известным статусом.

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза, данные Tranzila, сохранённые в заказах, и журналы плагина (включая ротированные файлы журналов) удаляются только если была включена опция Delete data on uninstall. Иначе они сохраняются для повторной установки. Существующие заказы сохраняют примечания об оплате и ID транзакций.

Tranzila является товарным знаком её правообладателя. Этот плагин не связан с Tranzila и не одобрен компанией Tranzila.