VibeFox Tranzila for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

Currency: ILS, USD, EUR or GBP. For other customer 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. 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 store 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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_tranzila_payment_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_tranzila_payment_gateway.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_tranzila_payment_gateway-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Tranzila Payment Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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. The notification URL is sent with every payment, so you do not have to copy it anywhere.

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

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

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_tranzila_payment_gateway.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Tranzila Payment Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 3 to 7 for OpenCart 3. The settings page and its fields are the same in both versions.

A new install starts with the payment method turned off.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Tranzila Payment Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings 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 store is not supported. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, the page never rejects everything at once. An empty Title or one longer than 128 characters, an invalid terminal name, an invalid Trusted IP entry, a number field that is not a whole number, or an invalid Sort Order, Total, Geo Zone or order status is not saved: the page shows the message in a red block above the settings, and the field shows the previous value again. A number outside the allowed range is saved as the nearest allowed value, and the page tells you so, for example that 5000 is outside 400–1500 and was saved as 1500. All other fields are saved.

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, so it is required and can be at most 128 characters long. Default: Credit Card (Tranzila).

Description: the text shown to the customer at the Confirm Order step, above the confirm button. Default: Pay securely with your credit card on the Tranzila payment page.

Sort Order: the position of Tranzila among the payment methods at checkout. Leave it empty or enter a whole number (negative values are allowed).

Geo Zone: offer Tranzila only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Tranzila is offered. Leave it empty to offer Tranzila for any total.

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. To remove a saved password, tick Clear saved password on save under the field and click Save.

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 storefront language of the customer 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 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 gets the paid status only when the notification comes from a Trusted IP and its payment page token, order, terminal, amount and currency match the payment page. With the handshake, the token must also match. 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 puts the order in On hold status, and you confirm the payment manually after checking the Tranzila terminal.

Notification URL: shown for information. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_tranzila_payment_gateway/notify, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_tranzila_payment_gateway/payment/wcp_tranzila_payment_gateway.notify. It is built from the storefront address of your OpenCart installation. The URL is sent to Tranzila with every payment, so you do not have to enter it in the Tranzila terminal. It also works while the store is in maintenance mode (on OpenCart 4 a startup action of the extension lets the notification and the customer return through).

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 in On hold status for manual review, and a reported decline changes nothing.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only from a verified Tranzila notification. OpenCart has no On hold status, so the status you choose here is used, and an order note explains why. Each field below lists your OpenCart order statuses.

Order status after payment: the payment was confirmed by a verified notification (amount, currency, terminal and token match). Default: Processing.

On hold status: the payment needs your review: the amount, currency or handshake token differ, the notification could not be verified (no Trusted IP), or notifications are disabled and the customer came back from a successful payment page. Default: Pending. You can create your own status in System > Localisation > Order Statuses and select it here.

Refunded status: set when the payment is fully refunded from the order page. Default: Refunded.

Cancelled order status: the extension does not set it. An order in this status that is paid later is re-opened with a note to check stock. Default: Canceled.

Payment error status: the extension does not set it. An order in this status is paid by a later approved Tranzila payment. Default: Failed.

Advanced

Debug log: logs payment page, notification and refund events to tranzila_p_debug.log.php in the OpenCart logs folder (storage/logs, on OpenCart 4 system/storage/logs). The file cannot be opened from the web, and at 5 MB it is moved to tranzila_p_debug.old.log.php. 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 extension removes the settings and the log. The Tranzila transactions and refunds always stay, because old orders need them. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. The passwords are not exported.

Import: paste previously exported JSON and click Import to restore the settings. The saved passwords are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Credit Card (Tranzila)). At the Confirm Order step the customer sees your description and the note After you confirm, you will enter your card details on the secure Tranzila payment page. The order is confirmed once Tranzila confirms the payment. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the customer goes to a 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 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. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page.

Each display of the payment page is a new payment attempt with its own token (and handshake token). Reloading the page opens a new attempt for the order of the same customer session; a payment page link opened in another browser leads back to the checkout.

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. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update. When an order on hold is paid later, the customer gets the e-mail about the new order status. If the notification has already arrived, the customer sees the OpenCart order success 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. with the buttons Check again and Back to checkout.

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 the order stays without a status. On OpenCart 4 this message is shown above the checkout page. OpenCart 3 creates a new order every time the Confirm Order step is shown, OpenCart 4 updates the order of the checkout; a cart that is already paid by one of these orders is not charged again. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

OpenCart 4 keeps the order in the checkout until the success page is shown. After a declined payment the customer pays the same order again with a new payment attempt. If that order was closed meanwhile (for example you cancelled it), or it was paid for a cart that has changed since, the customer is sent back to the checkout with This order can no longer be paid. Please confirm your order again., and the next Confirm Order pays a new order.

If the payment page cannot be opened, for example when the handshake fails, the customer stays at the Confirm Order step with a short message above the button, such as Could not connect to Tranzila. Please try again in a moment. The technical reason is written to the log.

The extension 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 status (missing order): the customer was sent to the payment page and has not paid, the payment was declined, or the Tranzila notification has not arrived yet. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders. On OpenCart 4.1 such an order can also have the status Voided, which OpenCart sets when the confirm step is shown again; the extension counts it as an order without a status.

Order status after payment (default Processing): the payment was confirmed by a verified notification. A note shows the amount, the Tranzila transaction (index), the authorization number and the number of installments when there are any.

On hold status (default Pending): 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 status (default Refunded): the payment was fully refunded through the extension.

If a payment arrives for an order in the on-hold, cancelled or payment error status, the order gets Order status after payment; a cancelled order also gets a note asking you to check stock before shipping. If a second payment arrives for an order that is already paid or refunded, or for another order of a cart that is already paid, the order is not changed. A note on the paid order asks you to check it and refund the duplicate in the Tranzila terminal. Repeated notifications of the same transaction are ignored.

Notes are entries in the order History that the customer does not see.

VibeFox Tranzila Payment Gateway tab

In Sales > Orders open an order paid with Tranzila. At the bottom of the order page, next to History and Additional, the VibeFox Tranzila Payment Gateway tab shows the Transaction (index), the Authorization, the Terminal, the Status, the amounts Paid / refunded, the number of Installments, the refund form, the refund history, all Payment pages of the cart with their result and the Tranzila notes of the order. The tab is shown to users who have access to the extension.

Refunds

In the VibeFox Tranzila Payment Gateway tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), 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 modify orders (sale/order in System > Users > User Groups). 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. Otherwise the tab 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 tab 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 status without notifying the customer and without returning products to stock, like a manual status change. A partial refund does not change the status.

Product returns in Sales > Returns do not send money back through Tranzila. Refunds made in the Tranzila terminal are not reported to the store. Update the order manually if needed.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Tranzila Payment Gateway is the first block on Extensions > Extensions > Payments > VibeFox Tranzila Payment Gateway > Edit, 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 store. Below them are the line Product: opencart-payment-tranzila and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. 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 extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 customer's 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. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status: 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 extension 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. For developers whose store is behind a trusted reverse proxy, the extension triggers the OpenCart event wcp_tranzila_payment_gateway/remote_ip to set the IP.

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

Notification answers Bad request or Not found: the order, the payment page token, the terminal or the transaction index in the notification do not match a payment page 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 cart was being processed by another request at the same moment, or the order status could not be set. The log shows the reason. Check the payment in the Tranzila terminal.

Some orders are in the on-hold status: read the notes in the VibeFox Tranzila Payment Gateway tab. 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 tab says that the refund was not confirmed: check the Tranzila terminal before trying again. Without the right to modify orders the tab says You do not have permission to refund orders.

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

For developers: before the payment page is shown, the extension triggers the OpenCart event wcp_tranzila_payment_gateway/payment_page_params with the fields of the payment page and the order.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Tranzila Payment Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. The OpenCart event of the extension is removed too (on OpenCart 4 its events and its startup action, which lets the notification and the customer return through in maintenance mode). If Delete data on uninstall is on, the other settings (title, description, terminal, passwords, payment page, payment confirmation, logging) and the log are removed. If it is off, they are kept for a later re-install. The Tranzila transactions and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Tranzila Payment Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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