Overview
The Handshake API V2 is a fraud-prevention mechanism that generates a unique, time-limited transaction token (thtk) before the customer is directed to the payment page.
The token locks the transaction amount and details on Tranzila's servers. If the amount submitted on the checkout page does not match the amount registered in the handshake, the transaction is automatically blocked.
Handshake V2 is available for both integration types:
- iFrame (DirectNG) – pass the
thtktoken as a parameter alongside your regular iframe parameters. - Hosted Fields – pass the
thtkvalue in thefields.charge()call.
Requirements
⚠️ Token Module required – Using the Handshake solution requires the purchase of Tranzila's Token Module. Contact support@interspace.net to enable this feature.
For iFrame integration only – you must also enable Handshake in the terminal settings:
- Log in to my.tranzila.com.
- Go to Settings → Terminal → iFrame.
- Open the Advanced tab.
- Click Enable Hand Shake.
When using Handshake with Hosted Fields, no dashboard configuration is required.
Watch Out!
Once Handshake is activated on an iFrame terminal, all transactions must include a valid thtk. Requests without a handshake token will be rejected.
Authentication
Handshake V2 uses the same four-header HMAC-SHA256 authentication scheme used across all Tranzila V2 APIs. All four headers must be present in every request.
| Header | Description |
|---|---|
X-tranzila-api-app-key | Application key supplied by Tranzila |
X-tranzila-api-request-time | Request time sent in Unix format (large integer counting milliseconds from Jan 1st, 1970 00:00:00) |
X-tranzila-api-nonce | A 40 bytes NONCE – unique random string generated with any random bytes function |
X-tranzila-api-access-token | hash_hmac using 'sha256' on application key with secret + request-time + nonce |
📖 For full details, code examples in multiple languages, and security guidelines, see the Authentication Guide.
Handshake Token Lifecycle
- The
thtktoken is valid for 20 minutes from creation. - A successful charge resets the 20-minute timer, allowing direct retries.
- If the token expires, a new handshake request must be made before retrying.
Important: Server-Side Only
⚠️ This request must always be performed server-side. Never expose your
app_key,secret, or the handshake endpoint call in client-side JavaScript.