What is the Tranzila Handshake and do I need it?

It is a fraud-prevention mechanism that locks the transaction amount on Tranzila's servers before the customer reaches the payment page. Your server requests a token (thtk) first, and Tranzila charges the locked amount rather than whatever the browser sent. Without it the amount is a client-side parameter anyone can edit in developer tools, so yes - you need it, or a rigorous server-side amount check at minimum.

Is the Tranzila Handshake included by default?

No. It requires purchasing the Token Module and having it enabled on the terminal. This is a commercial prerequisite rather than a code change, so confirm it is active before quoting an integration - otherwise you discover mid-build that the architecture you planned depends on a purchasing decision by the client.

How does the Tranzila v2 Handshake API authenticate?

Through four HMAC-SHA256 request headers rather than a simple API key, against POST https://api.tranzila.com/v2/handshake/create. That means computing a signature server-side on every request. Some operations additionally require both the terminal name and the terminal password, and all of these are server-side secrets.

How do you test that the Tranzila Handshake is actually working?

Open developer tools, change the amount parameter in the DOM before the payment page loads, and complete the payment. If the Handshake is active the charge comes out at the correct locked amount. If the edited figure is what gets charged, the mechanism is not in effect - and that is exactly the exposure it exists to close.

Tranzila API Integration Guide

How Tranzila's iframe integration actually works, what the Handshake mechanism protects against, why it needs a paid module and four HMAC headers, and the amount-tampering attack you are exposed to without it.

Tranzila is one of the long-established Israeli payment gateways, and the common way to use it is an iframe: you embed a frame pointing at Tranzila, the customer enters card details inside it, and the data never passes through your server. So far, the same as most gateways.

What distinguishes this integration is the Handshake - and most people implementing it for the first time do not understand why it exists, so they skip it. This guide explains exactly what it protects against.

The iframe: the basics

The iframe base URL looks like this:

https://direct.tranzila.com/<terminalname>/iframenew.php

The terminal name is part of the path. Transaction parameters - amount, currency, customer details, free fields identifying the order - are passed into the frame.

Official documentation lives at docs.tranzila.com and is worth opening: Tranzila has several iframe variants, and the choice between them affects what you build.

The problem: the amount is in the browser's hands

Here is the scenario worth understanding before deciding to skip the Handshake.

If transaction parameters - including the amount - are passed into the iframe from the client side, then the amount exists in the browser's DOM. Anyone who opens developer tools can change it before the payment page loads.

The result: the user pays 1 shekel for a 500-shekel product. The gateway approves it, because as far as it is concerned that is the amount it was asked to charge. Your server receives a successful-transaction notification. If you do not cross-check the amount, you ship the product.

This is not a theoretical attack and it requires no special skill - it requires a browser.

The fix: Handshake

The Handshake is a fraud-prevention mechanism that solves this at the root. The idea: lock the transaction amount on Tranzila's servers before the customer reaches the payment page.

The flow:

Your server calls Tranzila with the transaction details, including the amount.
Tranzila generates a unique token - thtk - and associates the amount with it.
Your server passes the token into the page, and it is sent to the iframe alongside the other parameters.
Tranzila charges according to what it has locked - not according to what arrived from the browser.

Editing the amount in the DOM now changes nothing, because the binding value has been held server-side since issuance.

Two prerequisites worth knowing up front

1. It requires the paid Token Module. The Handshake is not available by default - it requires purchasing a module and enabling it on the terminal. That is a commercial requirement, not a line of code. Confirm it is enabled before quoting the work, or you discover mid-development that your planned architecture depends on a procurement decision.

2. Authentication is not trivial. The v2 Handshake works against:

POST https://api.tranzila.com/v2/handshake/create

and authenticates with four HMAC-SHA256 headers, not a simple API key. That means a computed signature server-side on every request. It is not hard work, but it is not an hour either - and if you planned to "add an API key" you will be surprised.

Some operations also require both the terminal name and the terminal password. Both are server-side secrets.

What still has to happen on your side

Even with the Handshake, three things remain yours:

Cross-check the returned amount against the order. Always. This is defence in depth - if something in the mechanism was not enabled the way you thought, this is the check that catches it.
Verify the response actually came from Tranzila. A public endpoint that marks orders paid is a target. Do not rely on the URL being secret.
Idempotency. The same notification can arrive twice. That must not mark two orders paid or ship twice.

Do not trust the browser redirect

As with every gateway: the path where the browser returns to your thank-you page is not reliable. A customer who closes the tab the moment the payment clears never gets there, and the order stays "pending" while the money has been taken.

Order state must be driven by a server-to-server notification. The redirect shows a thank-you screen and nothing more.

PCI and boundaries

The main benefit of the iframe is that card details are entered inside a Tranzila frame and never pass through you. That protection holds only as long as you do not touch them at all - not sent, not logged, not stored. The moment card details appear in one of your log lines is the moment the regulatory picture changes.

Pre-launch checklist

Confirm the Token Module is enabled on the terminal - before you start developing against it.
Confirm the signature is computed server-side only.
Test manually: change the amount in the DOM and confirm the charge still comes out correct. That is the test that proves the Handshake is genuinely active.
Test the case where the customer closes the tab right after paying.
Test a real failure, not only success.

For a comparison of the Israeli gateways, see Israeli payment gateways compared. For connecting payments to document issuance, see the Israeli invoicing API comparison.

Tranzila Integration: The iframe, the Handshake, and Why It Exists

Key takeaways