VibeFox Tranzila for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

Shop currency: ILS, USD, EUR or GBP. For other cart 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 the order page. 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 shop 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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Tranzila Payment Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

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

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

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

7. Turn on Enable/Disable, click Save and test a payment with the Tranzila test terminal.

On install the module creates the order status Tranzila payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Tranzila Payment Gateway > Configure. Each section has its own Save button, which saves the whole page. 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 default currency of the shop is not supported. When you save, an invalid terminal name, an invalid Trusted IP entry or a number field that is not a whole number is not saved: the page shows an error and the previous value is kept. A number outside the allowed range is saved as the nearest allowed value, and the page tells you so.

Tranzila

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

Title: the payment method name customers see at checkout and the title of the payment page. It is also the payment method name stored in the order. 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 the order page.

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

Saved passwords are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved passwords: tick a password and click Save to remove it. An empty field keeps the saved value.

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 customer's cart 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 shop asks Tranzila for a one-time token bound to the 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 created as paid only when the notification comes from a Trusted IP and its payment page token, cart, terminal, amount and currency match the payment page. With the handshake, the token must also match the payment page. The customer's return from the payment page never marks an order paid.

Notifications: confirm payments automatically with Tranzila notifications (notify URL). Default: on. When notifications are off, a customer who comes back from a successful payment page creates the order in Tranzila payment on hold, and you confirm the payment manually after checking the Tranzila terminal.

Notification URL: shown for information. With friendly URLs it looks like https://your-shop/module/wcp_tranzila_payment_gateway/notify, possibly with a language code. The URL is sent to Tranzila with every payment, so you do not have to enter it in 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 creates the order in Tranzila payment on hold for manual review, and a reported decline changes nothing.

Advanced

Debug log: logs payment page, notification and refund events to logs/tranzila_p_debug.log.php in the module folder. The file cannot be opened from the web. Warnings and errors are always logged, even when this option is off. Passwords, tokens and customer data are never written. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete data on uninstall: when on, uninstalling the module removes the settings and the logs. The Tranzila transactions and refunds and the order status Tranzila payment on hold always stay, because old orders need them. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Credit Card (Tranzila)) and sees the description and the note After you confirm, you will enter your card details on the secure Tranzila payment page. The order is created once Tranzila confirms the payment. After confirming, the customer goes to a payment page of your shop. There the Tranzila payment page opens in an iframe with the cart total in the cart currency, the billing details and a short list of the 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. No order exists yet at this point.

After a successful payment, Tranzila sends the customer back and the whole window moves on. The order is marked paid only after Tranzila confirms it with a notification. If the notification has already arrived, the customer sees the standard order confirmation page with Your payment with Tranzila has been received. If the order is on hold for review, the page shows Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed. If the notification has not arrived yet, a Payment confirmation 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. and a Check again button.

If the payment is declined or cancelled, the customer is back at checkout 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 cart is kept, and no order is created. Each time the payment page is opened, it is a new payment page with its own token.

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 button Choose another payment method. The technical reason is written to the log.

The notification works while the shop is in maintenance mode and is not blocked by the country restriction of your shop. The same payment page is used with the Classic and Hummingbird themes.

The module 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

No order yet: the customer was sent to the payment page and has not paid, the payment was declined, or the Tranzila notification has not arrived yet. Only the cart exists.

Payment accepted: the payment was confirmed by a verified notification. The payment is recorded with the Tranzila transaction index as the transaction ID, and a note shows the amount, the transaction, the authorization number and the number of installments when there are any.

Tranzila payment on hold: the payment was reported but not accepted automatically: the amount, the currency or the handshake token did not match, 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 note explains why. Check the payment in the Tranzila terminal and change the status manually.

Refunded: the payment was fully refunded through the module.

If a payment arrives for an order that was cancelled, it is set to Payment accepted again with a note asking you to check stock before shipping. If a second payment arrives for an order that is already paid 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.

Tranzila payment block

The order page shows a Tranzila payment block with the transaction index, the authorization number, the terminal, the status, the amount paid and refunded, the number of installments, the refund history, all Payment pages of the cart with their result and the Tranzila notes of the order.

Refunds

In the Tranzila payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Tranzila. Confirm the question Refund this amount via Tranzila? This cannot be undone. Full and partial refunds are supported. You need the right to edit orders; access to the Modules pages is not needed. The refund is made as a Tranzila credit transaction of the original payment, on the terminal that took it, in the amount and currency Tranzila actually charged. So after an amount or currency mismatch you can refund up to what the customer actually paid, not the order total.

The form is available when the terminal password is set and the order has a confirmed Tranzila transaction with an authorization number. Otherwise the block says why, for example Refunds need the terminal password (TranzilaPW) in the gateway settings. An order paid on another terminal than the one in the settings now (for example a test terminal) cannot be refunded from the order page; refund it in that Tranzila terminal.

If Tranzila does not accept the refund, the block shows the error, for example Tranzila declined the refund with the code and its meaning, and no refund is recorded. A successful refund is added to the refund history and the notes with the Tranzila credit transaction. A full refund sets the order to Refunded. A partial refund does not change the status.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Tranzila. Refunds made in the Tranzila terminal are not reported to the shop. Update the order manually if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Tranzila Payment Gateway is the first block on Modules > Module Manager > VibeFox Tranzila Payment Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-tranzila and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed by the Tranzila notification and the return to the shop, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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 cart currency is ILS, USD, EUR or GBP. The settings page shows a warning when the terminal name is missing or the default currency is not supported. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created: 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 the log; look at the Log field on the module page. 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. Developers whose shop is behind a trusted reverse proxy can set the IP with the actionTranzilaPRemoteIp hook.

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

Notification answers Bad request or Not found: the cart, the payment page token, the terminal or the transaction index in the notification do not match a payment page of this shop.

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

Notification answers Busy, retry: the cart was being processed by another request at the same moment, or the order could not be created (for example, the module is disabled). The log shows the reason. Check the payment in the Tranzila terminal; if it is approved there and no order was created, contact the customer or create the order manually.

Some orders are Tranzila payment on hold: read the notes in the Tranzila payment block. 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. If the answer of Tranzila is unexpected, the block says that the refund was not confirmed: check the Tranzila terminal before trying again.

Other currencies: the module supports ILS, USD, EUR and GBP only.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Tranzila Payment Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the settings and the logs are removed. If it is off, all settings are kept for a later re-install. The Tranzila transactions and refunds and the order status Tranzila payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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