VibeFox Tranzila for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 8.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Store currency: ILS, USD, EUR or GBP. For other currencies the payment method is hidden at checkout.

Tranzila terminal: you need the terminal name. The terminal password (TranzilaPW) is needed for the handshake and for refunds from WooCommerce. Some terminals also need a separate credit password (CreditPass) for refunds. The terminal name and passwords are provided by Tranzila: see your terminal settings or ask Tranzila support. Tranzila has no public sandbox. For testing, Tranzila gives you a separate test terminal; enter its name as the terminal name.

Real visitor IP: payment notifications are checked against the IP address of the Tranzila server. If your site is behind a proxy or CDN such as Cloudflare, the web server must pass the real visitor IP to PHP (REMOTE_ADDR).

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_tranzila_payment_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Tranzila > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter the Terminal name (supplier), and the Terminal password (TranzilaPW) if you use the handshake or refunds.

6. Keep Notifications on and check Trusted IP: it must list the IP addresses Tranzila sends notifications from. Confirm the list with Tranzila support.

7. Recommended: enable the handshake in the Tranzila terminal, allow your server IP there, then turn on Handshake in the plugin.

8. Turn on Enable/Disable and test a payment with the Tranzila test terminal.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Tranzila. Above the fields the page warns you when the terminal name is empty (the payment method is then hidden at checkout), when notifications are disabled or Trusted IP is empty (paid orders are then put on hold for manual review), when the handshake is on without a terminal password (the payment page cannot be opened) and when the store currency is not supported. When you save, an invalid terminal name or an invalid Trusted IP entry is not saved: the page shows an error and the previous value is kept. Numbers outside the allowed range are corrected to the nearest allowed value.

General

Enable/Disable: Enable Tranzila Payment Gateway turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Credit Card (Tranzila).

Description: the text shown under the payment method at checkout. Default: Pay securely with your credit card on the Tranzila payment page.

Terminal

Terminal name (supplier): your Tranzila terminal name, for example myshop. Letters, digits, "-" and "_" only. Until it is entered, the payment method is not shown at checkout. For testing, enter the name of your Tranzila test terminal.

Terminal password (TranzilaPW): the API password of the terminal. Needed for the handshake and for refunds from WooCommerce.

Refund password (CreditPass): only if your terminal requires a separate password for credit (refund) transactions. Leave it empty otherwise.

Payment page

Payment page version: the Tranzila page shown in the iframe.

Payment page language: the language of the Tranzila page: Site language, Hebrew, English, Russian, Spanish, German, French or Japanese. Default: Hebrew. Site language uses the language of the visitor's WordPress locale when it is one of these languages, otherwise English.

iFrame width (px): 300 to 1200. Default: 600. On small screens the frame is never wider than the page.

iFrame height (px): 400 to 1500. Default: 650.

Max installments: the maximum number of installments (tashlumim) the customer may choose on the payment page, up to 36. 0 or 1 means no installments. Default: 0. The terminal must be allowed to process installments.

Handshake: Lock the amount with a handshake token (recommended). Before opening the payment page, the store asks Tranzila for a one-time token bound to the order amount, so the amount cannot be changed in the browser. It requires the terminal password, the handshake to be enabled in the Tranzila terminal and the IP address of your server to be allowed there. Default: off.

Payment confirmation

Tranzila notifications are not signed. An order is marked paid only when the notification comes from a Trusted IP and its order key, terminal, amount and currency match the order. With the handshake on, the token must also match the payment page of the order. The customer's return from the payment page never marks an order paid.

Notifications: Confirm payments automatically with Tranzila notifications (notify URL). Default: on. The notification URL is sent to Tranzila with every payment, so you do not have to enter it in the Tranzila terminal. It looks like https://your-site/wc-api/tranzila_p_callback/ and is shown under the field. When notifications are off, a customer who comes back from a successful payment page puts the order on hold, and you confirm the payment manually after checking the Tranzila terminal.

Trusted IP: the IP addresses or CIDR ranges of the Tranzila servers that send notifications, separated by commas. Default: 80.244.170.7. Confirm the current list with Tranzila support. Notifications from other addresses are rejected. If the field is empty, notifications cannot be verified: a reported successful payment puts the order on hold for manual review, and a reported decline does not change the order.

Advanced

Debug log: Log payment page, notification and refund events writes to WooCommerce > Status > Logs, source wcp_tranzila_payment_gateway. Errors are always logged, even when this option is off. Passwords, tokens and customer data are never written. Default: off.

Delete data on uninstall: Delete the settings, logs and Tranzila order data when the plugin is deleted. Default: off.

Checkout

The customer chooses the payment method (by default Credit Card (Tranzila)) and clicks Continue to payment. The order is created with the status Pending payment, and the customer goes to the order payment page of your store. There the Tranzila payment page opens in an iframe with the order total in the order currency, the billing details and a short list of the ordered products. The page says Enter your card details on the secure Tranzila payment page below. If it does not load, click "Proceed to payment". The link Choose another payment method is under the frame. If installments are allowed, the customer chooses their number on the Tranzila page.

After a successful payment, Tranzila sends the customer back and the whole window moves to the order received page of your store. The order is marked paid only after Tranzila confirms it with a notification. Until then the page shows 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. If the order is on hold for review, it shows Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed.

If the payment is declined or cancelled, the customer comes back to the order payment page with the message The payment was not completed. You have not been charged — please try again or choose another payment method. When Tranzila reports a response code, the reason and the code are added, for example that the card has expired. The customer can pay again or choose another payment method.

If the payment page cannot be opened, for example when the handshake fails, the customer sees a short message such as Could not connect to Tranzila. Please try again in a moment. and the link Choose another payment method. The technical reason is written to the log.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. On the Pay for order page it is offered when the order currency is supported. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes one-time card payments only, on the Tranzila page. It has no saved cards or tokens, no subscriptions, no separate authorize and capture (J5), no Bit, Apple Pay or Google Pay buttons of its own (whatever your Tranzila payment page offers is shown inside the iframe) and no Tranzila invoices.

Orders and refunds

Order statuses

Pending payment: the customer was sent to the payment page and has not paid yet, or the Tranzila notification has not arrived yet.

Processing or Completed: the payment was confirmed by a verified notification. WooCommerce sets Processing, or Completed for orders that need no shipping. The order note shows the amount, the Tranzila transaction and the authorization number, and the number of installments when there are any. The transaction ID is the Tranzila transaction index.

On hold: the payment was received but not accepted automatically: the amount, the currency or the handshake token did not match the order, the notification could not be verified because Trusted IP is empty, or notifications are off and the customer came back from a successful payment page. The order note explains why. Check the payment in the Tranzila terminal and change the status manually.

Failed: Tranzila reported a declined payment for a pending order. The note shows the response code and its meaning. An order that is already paid is never set to Failed.

If a payment arrives for a cancelled order, the order is re-opened with a note asking you to check stock before shipping. If the customer switched to another payment method on the Pay for order page but paid in a Tranzila page that was still open, the payment method of the order is set back to Tranzila. If a second payment arrives for an order that is already paid, completed or refunded, the order is not changed. A note asks you to check it and refund the duplicate in the Tranzila terminal. Repeated notifications of the same transaction are ignored.

Refunds

Open the order, click Refund, enter the amount and click Refund via Credit Card (Tranzila) (the button shows the title of the payment method). Full and partial refunds are supported. The refund is made as a Tranzila credit transaction of the original payment. The button is available when the terminal password is set and the order has a confirmed Tranzila transaction with an authorization number. A successful refund is added to the order notes with the Tranzila credit transaction.

If Tranzila does not accept the refund, WooCommerce shows the error, for example Tranzila declined the refund with the code, and no refund is recorded. An order paid on another terminal than the one in the settings now (for example a test terminal) cannot be refunded from WooCommerce; refund it in that Tranzila terminal. Refunds made in the Tranzila terminal are not reported to the store. If needed, create a manual refund in WooCommerce without the Tranzila button.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Tranzila. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Tranzila is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Tranzila does not appear at checkout: check that the license is active, Enable/Disable is on, Terminal name (supplier) is filled in and the store currency (on the Pay for order page, the order currency) is ILS, USD, EUR or GBP. The settings page shows a warning when the terminal name is missing or the currency is not supported.

The payment went through, but the order stays Pending payment: the notification did not arrive or was rejected. Check that Notifications is on and that Trusted IP lists the addresses Tranzila sends notifications from. Errors are always written to WooCommerce > Status > Logs, source wcp_tranzila_payment_gateway. The message that an IP is not in the Trusted IP list means that the Trusted IP setting or your proxy configuration must be fixed: behind a proxy or CDN the web server must pass the real visitor IP to PHP.

Notification answers Forbidden: it came from an IP address that is not in Trusted IP.

Notification answers Bad request or Not found: the order, its order key, the terminal or the transaction index in the notification do not match an order of this store.

Notification answers Accepted for manual review: Trusted IP is empty, so the notification could not be verified. A successful payment puts the order on hold. Fill in Trusted IP to confirm payments automatically.

Notification answers Busy, retry: the order was being processed by another request at the same moment, and the notification was not applied. Check the payment in the Tranzila terminal; if the order still waits for payment and the payment is approved there, change the status manually.

Some paid orders are On hold: read the order note. The amount, the currency or the handshake token did not match, or the notification could not be verified (Trusted IP empty, or notifications disabled). Check the payment in the Tranzila terminal and change the status manually.

The payment page does not open with the handshake on: check the terminal name and the terminal password, that the handshake is enabled in the Tranzila terminal and that the IP address of your server is allowed there. The log shows the reason.

Refunds fail: refunds need Terminal password (TranzilaPW). Some terminals also require a separate credit password; enter it in Refund password (CreditPass). Orders paid on another terminal must be refunded in that terminal.

Other currencies: the plugin supports ILS, USD, EUR and GBP. Developers can adjust the list with the tranzila_p_currency_map filter.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the Tranzila data stored on orders and the logs of the plugin (including rotated log files) are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

Tranzila is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Tranzila.