Create Handshake Token

posthttps://api.tranzila.com/v2/handshake/create

Generates a unique handshake token (thtk) that locks the transaction amount on Tranzila's servers.

This endpoint must be called server-side, before presenting the payment page to the customer.

Flow: iFrame Integration

Server calls POST /v2/handshake/create with terminal_name and sum.
Tranzila returns thtk (verify error_code: 0).
Server passes thtk as a parameter to the iFrame URL alongside all other transaction parameters.
Customer fills in card details and submits the form.
Tranzila validates that the amount matches the handshake — if not, the transaction is rejected with error 912791.

Flow: Hosted Fields Integration

Server calls POST /v2/handshake/create with terminal_name and sum.
Tranzila returns thtk (verify error_code: 0).
Server passes thtk to the client page (e.g., via a hidden form field).
The Hosted Fields charge() call includes the thtk value:

JavaScript

fields.charge({
  terminal_name: 'myterminal',
  amount: document.getElementById('amount').value,
  thtk:   document.getElementById('thtk').value,
  // ... other optional fields
}, function(err, response) { ... });

Request

Headers

X-tranzila-api-request-timestringrequired

Request time sent in Unix format (large integer counting milliseconds from Jan 1st, 1970 00:00:00)

X-tranzila-api-app-keystringrequired

Application public key supplied by Tranzila

X-tranzila-api-noncestringrequired

A 40 bytes NONCE – unique random string generated with any random bytes function

X-tranzila-api-access-tokenstringrequired

hash_hmac using 'sha256' on application key with secret + request-time + nonce. Result must be a lowercase hex string.

Body

application/json

terminal_namestringrequired

The Tranzila terminal name associated with the merchant account. Must match the terminal used for the subsequent payment page charge.

Example:myterminal

sumnumberrequired

The transaction amount to lock in this handshake. > ⚠️ **This value must exactly match the amount submitted on the payment page.** > Any discrepancy will cause the transaction to be rejected with error `912791`.

Example:150

request_paramsobject

Optional free-form object for passing additional data related to the transaction, the customer, or the downstream processing flow. Any key-value pairs provided here will be stored with the handshake and returned back to you upon completion — useful for correlating the transaction with your internal records without requiring a separate lookup. Keys and value types are flexible; there are no reserved or required field names.

Example:{"name":"serial","user_id":12,"testo":333}

Responses

Handshake token created successfully. The thtk value is valid and ready to pass to the payment page.

Response body

response.json

JSON

1{
2  "error_code": 0,
3  "message": "Success",
4  "thtk": "w5129f9cdd2ab53675bbb675c6b59dc51df3b8ce5f"
5}
6