VibeFox Tranzila for Adobe Commerce — 帮助

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL extension.

Order 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. 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 store is behind a proxy or CDN such as Cloudflare, the web server must pass the real visitor IP to PHP (REMOTE_ADDR). The X-Forwarded-For header is ignored.

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

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-tranzila-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/TranzilaPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_TranzilaPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Tranzila Payment Gateway. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the Terminal name, and the Terminal password if you use the handshake or refunds. Keep Automatic notifications at Yes and check Trusted IP: it must list the IP addresses Tranzila sends notifications from. Confirm the list with Tranzila support. Recommended: enable the handshake in the Tranzila terminal, allow your server IP there, then set Handshake to Yes. Set Enable to Yes, click Save Config and test a payment with the Tranzila test terminal.

The module adds the Credit Card (Tranzila) payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates three tables for the Tranzila payment pages, refunds and processed transactions.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Tranzila Payment Gateway, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Delete settings on uninstall is read from the Default Config only. Save Config saves the whole page.

When you save, a wrong value is not saved: the page shows a warning, the previous value is kept and the other fields are saved. This happens for an invalid Terminal name (Tranzila terminal name is invalid. The previous value was kept.), an invalid Trusted IP entry, an iframe size or Maximum installments that is empty or not a whole number, an empty Title or a title longer than 128 characters, a Sort order that is not a whole number and a Minimum order total or Maximum order total that is not a number of 0 or greater. A whole number outside the allowed range is saved as the nearest allowed value with the warning Tranzila numeric value was clamped to the allowed range.

Under the license block the page shows Notification URL is sent with every payment page. and the notification URL: the storefront address of the default store view. When Enable is Yes, it also warns you about setup problems: Enter your Tranzila terminal name. (the payment method is then hidden at checkout), Automatic notifications are disabled. Verify payments in the terminal., Trusted IP is empty. Payments require manual review. and Handshake requires the terminal password. (the payment page then cannot be opened), followed by Supported currencies: ILS, USD, EUR, GBP. Tranzila has no public sandbox; use a separate test terminal. The fields are in one group, in the order below.

General

Enable: shows or hides the payment method at checkout. It is shown only when Terminal name is set and the order currency is ILS, USD, EUR or GBP. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit Card (Tranzila). Required, at most 128 characters.

Description: the text shown in the payment method list at checkout, when the customer selects the method. Default: Pay securely with your credit card on the Tranzila payment page.

Terminal

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

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

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

Magento stores the passwords encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved password, clear the field and click Save Config. Spaces at the beginning and the end are removed.

Payment page

Payment page: 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 locale of the store view of the order 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.

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

Handshake: locks 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 and currency, 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: No.

Payment confirmation

Tranzila notifications are not signed. An order is invoiced 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 payment page. The customer's return from the payment page never marks an order paid.

Automatic notifications: confirms payments automatically with Tranzila notifications. Default: Yes. The notification URL looks like https://your-store/wcptranzilapaymentgateway/checkout/notify/. It is sent to Tranzila with every payment page, for the store view of the order, so you do not have to enter it in the Tranzila terminal. When notifications are off, no notification URL is sent: a customer who comes back from a successful payment page puts the order On Hold without an invoice, and you check the payment in the Tranzila terminal.

Trusted IP: real notification peer IP or CIDR. X-Forwarded-For is ignored. Empty means manual review, never automatic payment. Enter the IP addresses or CIDR ranges of the Tranzila servers that send notifications, separated by commas or on separate lines. 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 without an invoice for manual review, and a reported decline changes nothing.

Advanced

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

Delete settings on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings and the log (see Uninstall). The license key is always removed. The Tranzila transactions and refunds always stay, so old orders can still be refunded. Default: No.

Log: shows the size and the latest entries of the log. Click Clear log to empty it. It is shown in the Default Config.

Conditions

Payment from applicable countries: All Allowed Countries offers the payment method for every country your store allows, Specific Countries only for the countries below.

Payment from specific countries: offer the payment method only for billing addresses in these countries.

Minimum order total: offer the payment method only from this order total, in the base currency of your store. Empty or 0 means no minimum.

Maximum order total: offer the payment method only up to this order total, in the base currency. Empty or 0 means no maximum.

Sort order: the position among the payment methods at checkout. A whole number.

Checkout

At the payment step the customer chooses the payment method (by default Credit Card (Tranzila)) and sees the description and the note You will be redirected to Tranzila to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The customer goes to the Pay with Tranzila page of your store. There the Tranzila payment page opens in an iframe with the order total in the order currency, the billing details (name, company, phone, address, city and e-mail) and a short list of the products. If the frame does not load, the customer clicks Proceed to payment. If installments are allowed, the customer chooses their number on the Tranzila page. Each time this page is opened, it is a new payment page with its own token.

After the payment, Tranzila sends the customer back and the whole window moves on. The order is marked paid only after Tranzila confirms it with a verified notification. Magento then creates the invoice with the Tranzila transaction index as the transaction ID and sends the order e-mail. If the notification has already arrived, the customer sees the standard order success page. Otherwise the Tranzila payment confirmation page shows Your payment is being confirmed or requires manual review. Do not pay again until the first attempt is checked. and a Check again link. The same page is shown when the order is on hold for review.

If Tranzila reports a decline by notification, the order is cancelled (the stock goes back). When the customer comes back, the cart is restored and the customer sees The Tranzila payment was not completed. Your cart was restored. When Tranzila reports a response code, the reason and the code are added, for example that the card has expired. A decline of an older payment page does not cancel the order while a newer payment page of the same order is open.

If the payment page cannot be opened, for example when the handshake fails, the order is cancelled, the cart is restored and the customer sees Tranzila payment page could not be opened. Please try again later. The technical reason is written to the log.

The module works with the standard Magento checkout. It 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. The payment method is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to the payment page, but Tranzila has not confirmed the payment yet. There is no invoice.

Processing: the payment was confirmed by a verified notification. The invoice is created 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.

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. No invoice is created, and the note explains why. Check the payment in the Tranzila terminal. A later verified notification of the same payment that matches the order releases the hold and creates the invoice. An order that you put on hold yourself stays on hold.

Canceled: Tranzila declined the payment, the payment page could not be opened, or the order was cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). A payment that arrives later for a cancelled order does not re-open it: a note asks you to check the funds, and the payment can be refunded from the order page.

Closed: the payment was fully refunded with a credit memo.

If a second payment arrives for an order that is already paid, the order is not changed and no second invoice is created. A note asks you to check it and refund the extra payment in the Tranzila terminal. Repeated notifications of the same transaction are ignored. The notes are order comments that the customer does not see.

Tranzila payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for a confirmed payment, Tranzila terminal, Tranzila authorization, Tranzila transaction and Tranzila installments. The customer sees only the payment method title. The Information tab also shows Tranzila payment history: every payment page of the order with its transaction, terminal, status and the amount requested and paid, and the Tranzila refund history. It is shown for old orders too, and also when the module is disabled.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back as a Tranzila credit transaction of the original payment. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Tranzila.

The refund is made in the currency Tranzila actually charged, on the terminal that took the payment, up to the amount paid minus the amounts already refunded. The current Terminal name must be the terminal of the payment and Terminal password must be set; otherwise Magento shows Restore the original Tranzila terminal and password before refunding. Credit password is sent when it is set. If Tranzila does not accept the refund, Magento shows Tranzila refund was not confirmed. Reconcile in the terminal before retrying. and the credit memo is not created. After a clear decline you can try again. After an unclear answer (for example a timeout) the refund is kept as unconfirmed, and further online refunds of that payment are refused with Earlier Tranzila refund is unconfirmed. Reconcile before another request.: check the Tranzila terminal, refund there if needed and create a credit memo with Refund Offline. After a successful refund Magento records it on the order with the Tranzila credit transaction as the transaction ID. A full refund closes the order.

Refund held Tranzila payment: an order without an invoice that has a received Tranzila payment (for example On Hold after a mismatch, or a late payment for a cancelled order) shows a refund form in Tranzila payment history. Enter the amount in the currency actually charged (Review refund amount in the actual payment currency), at most the amount paid, and click Refund held Tranzila payment. The refund is sent to Tranzila and added to the order notes; no invoice or credit memo is created. Admin users need the permission for credit memos.

Refunds made in the Tranzila terminal are not reported to Magento. Create a credit memo with Refund Offline or 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 row of the VibeFox Tranzila Payment Gateway group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-tranzila and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the payment method is not shown to customers at checkout. If a payment is started anyway, the order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed by the Tranzila notification, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Tranzila does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that Terminal name is filled in and that the order currency is ILS, USD, EUR or GBP. The settings page shows a warning when the terminal name is missing. Check Payment from applicable countries and Payment from specific countries against the customer's billing address, and Minimum order total and Maximum order total.

The payment went through, but the order stays Pending Payment: the notification did not arrive or was rejected. Check that Automatic notifications is Yes and that Trusted IP lists the addresses Tranzila sends notifications from. Errors are always written to the log; look at the Log field in the Default Config. Behind a proxy or CDN the web server must pass the real visitor IP to PHP. Developers whose store is behind a trusted reverse proxy can set the IP with the Magento event tranzila_p_remote_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 order was being processed by another request at the same moment, or an error occurred while the order was being updated. The log shows the reason. Check the payment in the Tranzila terminal.

The notification URL shows POST only in the browser: this is normal. The URL accepts only notifications from Tranzila.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. The order stays Pending Payment: check the payment in the Tranzila terminal.

Some orders are On Hold: read the order notes (see Order statuses). The amount, the currency or the handshake token did not match, or the notification could not be verified (Trusted IP empty, or notifications off). Check the payment in the Tranzila terminal, then handle the order manually or refund the payment with Refund held Tranzila payment.

The customer is back in the cart after Place Order with Tranzila payment page could not be opened: with 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. The order of that attempt is cancelled.

Refunds fail: refunds need Terminal password. Some terminals also require a separate credit password; enter it in Credit password. Orders paid on another terminal must be refunded in that terminal. If the answer of Tranzila is unclear, check the Tranzila terminal before trying again.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded with a credit memo; use Refund held Tranzila payment or the Tranzila terminal.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_TranzilaPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_TranzilaPayment to remove the data, then bin/magento module:disable Vibefox_TranzilaPayment, delete the folder app/code/Vibefox/TranzilaPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Delete settings on uninstall is Yes, the gateway settings and the log are removed too. If it is No, the settings are kept for a 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 invoices, payment notes and transaction IDs.

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