Tranzila Payment Gateway

Tranzila Payment Gateway

Overview

Tranzila is one of Israel's leading payment processors (solek), operating since 1999. It connects to the Shva network (reshet shva) -- Israel's central card processing infrastructure -- and supports all Israeli card issuers: Isracard, Visa Cal, and Max (formerly Leumi Card).

This skill guides integration with Tranzila for accepting credit card payments (slikat kartis ashrai) in Israeli applications.

Official docs: https://docs.tranzila.com/

Test credentials: Visa test card 4444333322221111, Isracard test 12312312, any CVV (e.g. 333), any future expiry. Configure your terminal for sandbox mode via the Tranzila dashboard.

Instructions

Step 1: Choose Integration Pattern

Help the user select the right approach based on their needs:

Most Israeli merchants start with Iframe for collecting payments, then use API V2 for server-side operations like token charging and refunds.

Step 2: Set Up Authentication

Tranzila uses different credentials depending on the integration:

For Iframe / Legacy CGI:

• supplier -- Terminal name (provided by Tranzila)
• TranzilaPW -- Transaction password

For API V2 (api.tranzila.com/v1): authentication is a 4-header HMAC-SHA256 handshake, NOT a single key header. Every request must send all four:

• X-tranzila-api-app-key -- your public application key
• X-tranzila-api-request-time -- current Unix time in SECONDS
• X-tranzila-api-nonce -- a random nonce (about 40 bytes)
• X-tranzila-api-access-token -- hmac_sha256(secret + request_time + nonce, app_key) (HMAC-SHA256 of the app key, keyed with secret concatenated with the request-time and nonce)

You get both a public app key and a secret key when you enrol in API V2. A request with only X-tranzila-api-app-key is rejected. (Base URL is https://api.tranzila.com/v1; "API V2" is the auth-generation name, not a /v2 path.) Confirm the exact concatenation order in the Authentication page at docs.tranzila.com before shipping.

Remind the user to store credentials securely (environment variables, secrets manager) and never commit them to source control.

Step 3: Implement the Payment Flow

Option A: Hosted Fields (Recommended for Custom UX)

Hosted Fields let you design your own checkout form while Tranzila securely handles card inputs:

1. Include the Tranzila Hosted Fields JS on your page 2. Create container <div> elements for card number, expiry, and CVV 3. Initialize fields with your terminal name and styling options 4. On submit, the JS generates a TranzilaTK token without card data touching your server 5. Send the token to your backend for charging via API V2

This gives full design control while maintaining SAQ-A-EP PCI compliance. Refer to the Hosted Fields section under https://docs.tranzila.com/ (deep slug paths change frequently; navigate from the Payments & Billing index).

Webhook signature verification. When Tranzila POSTs the result to your notify_url, do NOT trust it on inbound shape alone. Verify by either (a) issuing a follow-up server-to-server confirm API call against tranzila71dt.cgi to confirm the transaction id, or (b) validating the myid you provided round-trips back, or (c) signing your own checksum into the form fields and verifying it on receipt. Without this step, anyone with your notify_url can fake transaction-success callbacks.

Option B: Iframe Integration (Quick Start)

1. Embed the Tranzila iframe in your checkout page:

• URL: https://direct.tranzila.com/{supplier}/iframenew.php
• Add query parameters: sum, currency, cred_type
• Default mode creates a token (J5); use J4 for one-time charge

2. Handle the response via your notify_url:

• Tranzila POSTs results to your server
• Check Response field: 000 = approved
• Store TranzilaTK (token) for future charges

3. Confirm transaction server-side (recommended):

• Use the three-sided handshake to verify the transaction is genuine

Option C: Server-to-Server via API V2

For token charging, refunds, and operations that don't involve card entry:

Charge a token:

POST https://secure5.tranzila.com/cgi-bin/tranzila31tk.cgi
Content-Type: application/x-www-form-urlencoded

supplier={terminal}&TranzilaPW={password}&TranzilaTK={token}&expdate={MMYY}&sum={amount}&currency=1&cred_type=1

Process a refund: Use tranmode=C{index} with the original ConfirmationCode and index from the original transaction.

Consult references/api-parameters.md for the complete parameter reference.

Step 4: Handle Israeli-Specific Payment Types

Israeli payments have unique features that differ from international processing:

Installments (Tashlumim):

• Set cred_type=8 for regular installments
• Parameters: npay (number of payments minus 1), fpay (first payment), spay (subsequent payments)
• The sum of fpay + (npay * spay) must equal the total sum
• Not all terminals are authorized for installments (you get an error if the terminal is not enabled for them; check the exact code in the official table)

Credit Types (cred_type):

Currency codes (matbea):

Israeli ID (teudat zehut): Some transactions require myid parameter -- a 9-digit Israeli ID number (mispar zehut).

Step 5: Implement Tokenization for Recurring Payments (hora'ot keva)

Tokens (asmachta) let you charge returning customers without handling card data again:

1. Create token during first payment:

• Iframe: Default behavior (J5 mode) returns TranzilaTK
• API: Use tranmode=K (token only), VK (verify + token), or AK (charge + token)

2. Store the token securely:

• Token is a 19-character string (last 4 digits match the card)
• Store token, expiry date, and card last-4 in your database
• Token has no value without your terminal credentials

3. Charge the token later:

• Use the /cgi-bin/tranzila31tk.cgi endpoint
• Include TranzilaTK, expdate, sum, and currency

Step 6: Add 3D Secure (if required)

3D Secure V2 adds cardholder authentication. Consult references/3ds-flow.md for the full redirect-based flow. Key points:

• 3DS changes the payment flow to include a bank authentication step
• Response includes additional fields for authentication status
• Some Israeli issuers may not support 3DS for all card types

Step 7: Accept Bit Payments

Tranzila supports Bit (Israel's popular mobile payment app) through a dedicated Bit API, not a flag on the card-charge CGI. It has its own Bit - Init and Bit - Refund POST endpoints under https://api.tranzila.com/v1 using the same 4-header HMAC auth as the rest of API V2.

1. Call the Bit Init endpoint via the API -- Tranzila returns a Bit payment URL 2. Redirect the customer to the Bit URL or display a QR code 3. Customer approves payment in the Bit app 4. Tranzila sends the result to your notify_url 5. Bit refunds use the dedicated Bit Refund endpoint, not the card refund flow

Bit constraints (from the docs): NIS only, transaction sum must be above 5 NIS, and the merchant needs a Visa or Isracard identifier, Max-only merchants are not offered Bit at this time. Bit does not support Hosted Fields or 3DS. Do not assume a bit=1 / bit_url parameterization on the legacy CGI; use the dedicated Bit API. Refer to https://docs.tranzila.com/docs/payments-billing/dcljft4y7sgj2-bit.

Step 8: Generate Payment Request Links

Payment Requests (TRAPI) let you send payment links via email or SMS without building a checkout page:

1. Create a payment request via API with amount, description, and customer contact 2. Tranzila generates a secure payment link 3. Send the link to the customer (Tranzila can send automatically via email/SMS) 4. Customer clicks the link and pays on a Tranzila-hosted page 5. You receive the result via webhook

This is useful for invoicing, phone orders, or any scenario where you need to collect payment without an embedded form.

Step 9: Set Up Standing Orders (Recurring Payments)

For automated recurring billing beyond simple token charging, Tranzila offers Standing Orders:

1. Create a standing order with payment schedule (amount, frequency, start/end dates) 2. Tranzila automatically charges the customer on schedule 3. Monitor results via the Reports API or webhook notifications 4. Cancel or modify standing orders via API

Standing orders are a paid feature -- contact Tranzila to enable on your terminal. Refer to Tranzila's documentation for detailed standing order setup instructions.

Step 10: Generate Invoices

Tranzila has an Invoicing API for generating digitally-signed tax documents approved by the Israeli Income Tax Authority:

1. Create invoices tied to transactions or standalone 2. Invoices are digitally signed for tax compliance 3. Supports tax invoices, receipts, and credit notes 4. Can be auto-generated with PayPal payments

Israel Tax Authority allocation number (mispar haktza'a), mandatory for B2B invoices over thresholds. Since 2025-01-01 the ITA requires every B2B tax invoice over a threshold to carry an allocation number obtained from SHAAM via API. Threshold schedule: NIS 20,000 (from Jan 2025), NIS 10,000 from Jan 2026, NIS 5,000 from Jun 2026. Without the allocation number, the buyer cannot deduct input VAT on the invoice. If you generate invoices through Tranzila's Invoicing API, confirm with Tranzila support that allocation-number requests are wired through SHAAM for invoices at or above the current threshold; if not, fall back to a separate invoicing provider (Green Invoice, Morning, etc.) that does integrate with SHAAM, or request allocation numbers directly via the ITA portal.

Refer to Tranzila's invoicing documentation for the complete invoicing API reference.

Step 11: Handle Errors

Check the Response field in every transaction result. 000 means approved -- anything else is a decline or error.

Important: the HTTP status of an API V2 call is 200 even on a declined/failed transaction. The HTTP 200 does NOT mean success; read the Response / response-code field in the body for the actual SHVA result. And there are TWO separate code spaces: the SHVA/issuer codes (hundreds of codes, e.g. card-issuer refusals are in the 300s, installment errors in the 400s) and a separate 3D-Secure code set (900-930). Do not assume codes from Stripe or other gateways.

A few confirmed codes (verify the rest against references/error-codes.md and the official "Transaction Response Codes" page at docs.tranzila.com):

For the full reference (260+ SHVA codes plus the separate 900-930 3DS set), consult references/error-codes.md and verify against the official docs, do NOT hardcode codes from memory.

Examples

Example 1: Accept a One-Time Payment

User says: "I need to add credit card payments to my Node.js checkout page" Actions: 1. Choose: Iframe integration (minimal PCI scope) 2. Guide: Embed iframe with supplier name, sum, currency=1 (ILS) 3. Implement: Server-side notify_url handler to capture response 4. Validate: Check Response=000, store ConfirmationCode Result: Working checkout that accepts Israeli credit cards via embedded form.

Example 2: Set Up Monthly Subscription

User says: "I want to charge customers 99 NIS every month automatically" Actions: 1. First payment: Iframe with token creation (J5 mode) 2. Store: Save TranzilaTK and expdate from response 3. Monthly: Cron job calls tranzila31tk.cgi with stored token 4. Handle: Check for expired cards, declined tokens Result: Recurring monthly billing using tokenized cards.

Example 3: Process Installment Payment

User says: "My customer wants to pay 6,000 NIS in 3 tashlumim" Actions: 1. Set: cred_type=8 (installments) 2. Calculate: fpay=2000, spay=2000, npay=2 (3 payments total) 3. Verify: Terminal authorized for installments 4. Process: Transaction with installment parameters Result: Payment split into 3 equal installments of 2,000 NIS.

Example 4: Refund a Transaction

User says: "I need to refund transaction from last week, confirmation code 0283456" Actions: 1. Use: tranmode=C0 (cancel first transaction in batch) 2. Include: Original ConfirmationCode and index 3. Set: sum to refund amount (partial or full) 4. Verify: Response=000 for successful refund Result: Refund processed and linked to original transaction.

Example 5: Accept Bit Payment

User says: "I want to let customers pay with Bit on my website" Actions: 1. Call the dedicated Bit Init endpoint (api.tranzila.com/v1, 4-header HMAC auth) -- not a flag on the card CGI 2. Redirect: Send customer to the Bit payment URL from the response (or show a QR) 3. Handle: Receive payment confirmation at notify_url 4. Verify: Check the response code for a successful Bit payment 5. Note constraints: NIS only, sum > 5 NIS, merchant needs a Visa/Isracard identifier (Max-only merchants not supported) Result: Customers can pay using Israel's Bit mobile wallet alongside credit cards.

Example 6: Send Payment Link via SMS

User says: "I need to collect payment from a customer over the phone" Actions: 1. Create: Payment request via TRAPI with amount and customer phone number 2. Send: Tranzila sends SMS with payment link automatically 3. Wait: Customer opens link and pays on Tranzila's hosted page 4. Confirm: Receive webhook notification when payment completes Result: Payment collected remotely without building a checkout page.

Community Libraries

• tranzilajs (TypeScript/Node.js) -- Modern SDK with HMAC auth, Bit payments, credit card ops, iframe generation. Install: npm install tranzilajs. See: https://github.com/NirTatcher/tranzilajs
• omnipay-tranzila (PHP/Omnipay) -- Community gateway plugin
• active_merchant_tranzila (Ruby) -- ActiveMerchant gateway adapter

Bundled Resources

References

• references/api-parameters.md -- Complete Tranzila API parameter reference for both legacy CGI and API V2 endpoints, including authentication headers, transaction parameters, token operations, and installment fields. Consult when constructing API requests or debugging unexpected parameter behavior.
• references/error-codes.md -- Full listing of Tranzila response codes (000-999) with meanings and recommended handling. Consult when a transaction returns a non-000 response code.
• references/3ds-flow.md -- Step-by-step 3D Secure V2 implementation guide for Tranzila, including redirect flow, authentication parameters, and fallback handling. Consult when adding 3DS to an existing integration.

Scripts

• scripts/validate_tranzila_response.py -- Validates a Tranzila transaction response: checks response code, verifies required fields are present, and flags common issues (missing confirmation code, mismatched amounts). Run: python scripts/validate_tranzila_response.py --help

Gotchas

• Tranzila API uses form-encoded key-value pairs (not JSON). Agents default to JSON request bodies, which Tranzila will reject or ignore. Send requests as application/x-www-form-urlencoded.
• Tranzila's test mode uses the same endpoint as production but with a different supplier parameter. Agents may accidentally send test transactions to the production terminal or vice versa.
• The response format from Tranzila is a plain-text key=value string separated by newlines, not JSON. Agents may try to JSON.parse() the response, which will throw an error.
• Israeli credit card numbers have different BIN ranges than US/European cards. Tranzila validates cards locally, so test cards from Stripe or other international gateways will not work.

Reference Links

Troubleshooting

Error: "Transaction rejected with a non-000 response code"

Cause: Missing or invalid parameters, a card-issuer decline, or a config/permission issue. Remember the HTTP status is 200 even on failure, read the Response field for the actual code. Solution: Verify all required parameters are present: supplier, TranzilaPW, sum, ccno (or TranzilaTK), expdate. Check parameter names are exact (case-sensitive). Look up the exact response code in the official Transaction Response Codes page (see references/error-codes.md), do not guess its meaning.

Error: "Terminal not authorized for installments / Amex"

Cause: Your Tranzila terminal does not have installment (or Amex) permissions enabled. Solution: Contact Tranzila support (073-222-4444) to enable installment or Amex processing on your terminal.

Error: "Token charge fails but iframe worked"

Cause: Common when using wrong endpoint or missing expdate Solution: Token charges use /cgi-bin/tranzila31tk.cgi (not tranzila31.cgi). Include both TranzilaTK and expdate parameters.

Error: "Transaction approved in test but not production"

Cause: Test and production terminals behave differently Solution: Verify your production terminal name and password. Some operations (like void) behave differently in production. Check with Tranzila support if behavior diverges.

Error: "Currency mismatch"

Cause: Using wrong endpoint for currency Solution: ILS and USD use tranzila31.cgi. Multi-currency (EUR, GBP, etc.) requires tranzila36a.cgi.

3D Secure V2 Implementation for Tranzila

Overview

3D Secure V2 (3DS2) adds a cardholder authentication step between your server and the card issuer. It shifts fraud liability from the merchant to the issuer for authenticated transactions. Tranzila implements 3DS2 via a redirect flow -- the customer is redirected to their bank's authentication page, then returned to your site.

Flow Diagram

1. Customer submits payment on your site
2. Your server sends transaction to Tranzila with 3DS parameters
3. Tranzila returns a redirect URL (if 3DS is required)
4. Customer is redirected to bank authentication page
5. Customer completes authentication (password, OTP, biometric)
6. Bank redirects customer back to your notify_url
7. Tranzila POSTs final result to your server
8. Your server checks Response and 3DS authentication status

Enabling 3DS

Add these parameters to your standard transaction request:

3DS enrollment is typically configured at the terminal level by Tranzila. Contact Tranzila support (073-222-4444) to enable 3DS on your terminal. Once enabled, eligible transactions are automatically routed through the 3DS flow.

For iframe integrations, 3DS is handled within the iframe -- no additional server-side parameters are needed.

Response Fields for 3DS

After the authentication flow completes, Tranzila includes these additional fields:

Authentication Status Values

ECI Values

Fallback Handling

Not all transactions will go through 3DS. Handle these cases:

Card/issuer does not support 3DS:

• Tranzila processes the transaction as a regular (non-3DS) charge
• eci will be 07 (Visa) or empty
• Liability remains with the merchant
• No action needed -- the transaction completes normally

Customer abandons authentication:

• No callback is received at notify_url
• Implement a timeout (recommended: 15 minutes) on your side
• Display a "payment not completed" message and allow retry

3DS system unavailable:

• Tranzila falls back to non-3DS processing
• Transaction may still succeed with Response=000 but without liability shift
• Log the eci value to track which transactions were authenticated

Response code 900:

• Authentication explicitly failed
• Do not retry automatically with 3DS
• Offer the customer the option to retry or use a different card

Israeli Issuer Notes

• Isracard, Visa Cal, and Max (formerly Leumi Card) all support 3DS V2 for Visa and Mastercard branded cards
• American Express cards issued in Israel have limited 3DS support -- most Amex transactions fall back to non-3DS
• Diners Club cards generally do not support 3DS in Israel
• Israeli issuers commonly use SMS OTP for authentication (rather than app-based or biometric)
• Some Israeli business cards (kartis ishi) may be exempt from 3DS requirements based on terminal configuration
• Test 3DS in Tranzila's sandbox environment before going live -- sandbox simulates both successful and failed authentication flows

Tranzila API Parameter Reference

Endpoints

Legacy CGI Endpoints

All legacy endpoints accept POST with Content-Type: application/x-www-form-urlencoded.

Iframe Endpoint

https://direct.tranzila.com/{supplier}/iframenew.php?sum=100&currency=1&cred_type=1

• J5 mode (default): Creates a token -- card is not charged. Use token via tranzila31tk.cgi to charge later.
• J4 mode: One-time charge -- card is charged immediately, no token returned.

API V2 Authentication

Base URL is https://api.tranzila.com/v1 ("API V2" is the auth-generation name, not a /v2 path). Authentication is a 4-header HMAC-SHA256 handshake; ALL four headers are required:

POST https://api.tranzila.com/v1/{resource}
X-tranzila-api-app-key: {public app key}
X-tranzila-api-request-time: {unix time in seconds}
X-tranzila-api-nonce: {~40-byte random nonce}
X-tranzila-api-access-token: {hmac_sha256(secret + request_time + nonce, app_key)}
Content-Type: application/json

You enrol in API V2 to get a public app key and a secret key; the access-token is the HMAC-SHA256 of the app key, keyed with the secret concatenated with the request-time and nonce. A request with only X-tranzila-api-app-key is rejected. These headers replace supplier + TranzilaPW. Confirm the exact concatenation order on the Authentication page at docs.tranzila.com before shipping.

Common Parameters

Authentication

Transaction Details

Credit Types (cred_type)

Installment Parameters (when cred_type=8 or 9)

Rule: fpay + (npay * spay) must equal sum.

Example -- 3 payments of 100 NIS each (total 300):

sum=300&cred_type=8&npay=2&fpay=100&spay=100

Transaction Mode (tranmode)

Token Parameters

Callback / Notification

Response Fields

Domain coverage checklist, tranzila-payment-gateway

Anchor for expert review. Scope: integrating Tranzila payments (iframe, hosted fields, API V2, tokens, installments, refunds, 3DS, Bit) into Israeli apps.

Must cover (core)

• Integration patterns + PCI scope (Iframe SAQ-A, Hosted Fields SAQ-A-EP, API V2 SAQ-D).
• Auth: legacy supplier+TranzilaPW; API V2 = 4-header HMAC-SHA256 (app-key + request-time + nonce + access-token) at api.tranzila.com/v1.
• Endpoints: direct.tranzila.com/{supplier}/iframenew.php; secure5.tranzila.com CGIs (tranzila31/36a/31tk).
• Israeli payment types: installments (cred_type=8, npay/fpay/spay, fpay+npay*spay=sum), credit types, currency codes, tokenization (TranzilaTK, tranmode K/VK/AK), refund (tranmode=C{index}).
• Error handling: HTTP 200 on failure, read Response field; two code spaces (SHVA + 3DS 900-930); verify codes against official docs.
• Bit dedicated API + constraints (NIS, >5 NIS, Visa/Isracard, Max-only not supported).
• Webhook signature verification (don't trust inbound shape).
• ITA allocation number for B2B invoices (20K/10K/5K schedule).

Out of scope (explicit)

• Cardcom (use cardcom-payment-gateway), general accounting.

Authoritative sources

• Tranzila docs: https://docs.tranzila.com/
• Tranzila site: https://www.tranzila.com
• tranzilajs: https://github.com/NirTatcher/tranzilajs

Tranzila Response Codes

000 = approved. Any other value is a decline or error.

How Tranzila returns codes (read this first)

• HTTP 200 does NOT mean the transaction succeeded. On API V2 the HTTP status is 200 even for a declined or failed transaction; the real result is the Response / response-code field in the body.
• There are two separate code spaces:
• SHVA / issuer codes (the large numeric table, hundreds of codes): card-issuer refusals cluster in the 300s, installment-related errors in the 400s, PinPad errors in the 700s, PayPal-specific errors in the 950s.
• 3D Secure codes (a separate set, 900-930): e.g. 900 = 3DS authentication failed.
• Do NOT reuse codes from Stripe, Cardcom, or other gateways. Tranzila's codes are gateway-specific.
• The authoritative, complete list is the official "Transaction Response Codes" page in the Tranzila docs (260+ SHVA rows + the 3DS tab). Always verify a specific code there before acting on it; do not hardcode codes from memory.

Confirmed common codes

(Every specific code above should still be re-confirmed against the official Transaction Response Codes page; the SHVA code space has hundreds of entries and is easy to mis-cite.)

Categories to expect (verify the exact code in the official table)

• Card-issuer refusals (insufficient funds, restricted card, stolen, etc.): generally in the 300s.
• Installment / credit-type errors: generally in the 400s (401-406).
• 3D Secure: 900-930.
• PinPad / terminal hardware: 700s.
• PayPal-specific: 950s.

When you hit a non-000 code, look it up by exact number in the official Transaction Response Codes page rather than inferring its meaning. Build error handling to fall back to a generic "payment could not be completed, please try another card or contact your bank" message for any code you have not explicitly mapped.

שער תשלומים טרנזילה

הוראות

שלב 1: בחירת דפוס אינטגרציה

עזרו למשתמש לבחור את הגישה המתאימה לצרכיו:

רוב בתי העסק הישראליים מתחילים עם Iframe לאיסוף תשלומים, ואז משתמשים ב-API V2 לפעולות צד-שרת כמו חיוב טוקנים והחזרים.

שלב 2: הגדרת אימות

טרנזילה משתמשת באישורים שונים לפי אינטגרציה:

עבור Iframe / Legacy CGI:

• supplier -- שם מסוף (מסופק על ידי טרנזילה)
• TranzilaPW -- סיסמת עסקה

עבור API V2 (api.tranzila.com/v1): האימות הוא handshake של HMAC-SHA256 עם 4 כותרות, לא כותרת מפתח יחידה. כל בקשה חייבת לשלוח את כל הארבע:

• X-tranzila-api-app-key -- מפתח האפליקציה הציבורי
• X-tranzila-api-request-time -- זמן Unix נוכחי בשניות
• X-tranzila-api-nonce -- nonce אקראי (כ-40 בתים)
• X-tranzila-api-access-token -- hmac_sha256(secret + request_time + nonce, app_key) (HMAC-SHA256 של מפתח האפליקציה, עם מפתח הצפנה של ה-secret משורשר עם זמן הבקשה וה-nonce)

בהרשמה ל-API V2 מקבלים גם מפתח אפליקציה ציבורי וגם מפתח secret. בקשה עם X-tranzila-api-app-key בלבד נדחית. (כתובת הבסיס היא https://api.tranzila.com/v1; "API V2" הוא שם דור-האימות, לא נתיב /v2.) אמתו את סדר השרשור המדויק בעמוד האימות ב-docs.tranzila.com לפני העלייה לפרודקשן.

הזכירו למשתמש לאחסן אישורים בצורה מאובטחת (משתני סביבה, מנהל סודות) ולעולם לא לשמור אותם בקוד המקור.

שלב 3: מימוש זרימת התשלום

אפשרות א: Hosted Fields (מומלץ לעיצוב מותאם)

Hosted Fields מאפשרים לכם לעצב את טופס התשלום שלכם בזמן שטרנזילה מטפלת בקלט הכרטיס בצורה מאובטחת:

1. הוסיפו את Hosted Fields JS של טרנזילה לדף שלכם 2. צרו אלמנטי <div> עבור מספר כרטיס, תפוגה, ו-CVV 3. אתחלו את השדות עם שם המסוף ואפשרויות עיצוב 4. בשליחה, ה-JS מייצר טוקן TranzilaTK ללא שנתוני כרטיס עוברים דרך השרת שלכם 5. שלחו את הטוקן לשרת שלכם לחיוב דרך API V2

זה נותן שליטה מלאה בעיצוב תוך שמירה על עמידה ב-SAQ-A-EP PCI. ראו את חלק Hosted Fields תחת https://docs.tranzila.com/ (קישורי slug עמוקים משתנים, נווטו מהאינדקס Payments & Billing).

אימות חתימה ב-webhook. כש-Tranzila שולח POST לתוצאה ל-notify_url, אל תסמכו על הצורה של הקריאה. אמתו על-ידי קריאת confirm שרת-לשרת מול tranzila71dt.cgi כדי לאשר את מזהה העסקה, או על-ידי בדיקה ש-myid שהעברתם חוזר זהה, או על-ידי checksum שאתם חותמים בעצמכם בשדות הטופס ובודקים בקבלה. בלי זה, כל מי שיודע את ה-notify_url יכול לזייף הצלחות עסקה.

אפשרות ב: אינטגרציית Iframe (התחלה מהירה)

1. הטמיעו את ה-iframe של טרנזילה בדף התשלום:

• כתובת: https://direct.tranzila.com/{supplier}/iframenew.php
• הוסיפו פרמטרים: sum, currency, cred_type
• מצב ברירת מחדל יוצר טוקן (J5); השתמשו ב-J4 לחיוב חד-פעמי

2. טפלו בתגובה דרך ה-notify_url:

• טרנזילה שולחת POST לשרת שלכם
• תבדקו שדה Response: 000 = אושר
• שמרו TranzilaTK (טוקן) לחיובים עתידיים

3. אשרו עסקה בצד השרת (מומלץ):

• השתמשו בלחיצת יד תלת-צדדית לאימות שהעסקה אמיתית

אפשרות ג: שרת-לשרת דרך API V2

לחיוב טוקנים, החזרים ופעולות שאינן כוללות הזנת כרטיס:

חיוב טוקן:

POST https://secure5.tranzila.com/cgi-bin/tranzila31tk.cgi
Content-Type: application/x-www-form-urlencoded

supplier={terminal}&TranzilaPW={password}&TranzilaTK={token}&expdate={MMYY}&sum={amount}&currency=1&cred_type=1

ביצוע החזר: השתמשו ב-tranmode=C{index} עם ConfirmationCode וה-index מהעסקה המקורית.

עיינו ב-references/api-parameters.md למדריך הפרמטרים המלא.

שלב 4: טיפול בסוגי תשלום ייחודיים לישראל

לתשלומים ישראליים יש מאפיינים ייחודיים שנבדלים מעיבוד בינלאומי:

תשלומים (tashlumim):

• הגדירו cred_type=8 לתשלומים רגילים
• פרמטרים: npay (מספר תשלומים פחות 1), fpay (תשלום ראשון), spay (תשלומים הבאים)
• הסכום של fpay + (npay * spay) חייב להיות שווה ל-sum הכולל
• לא כל המסופים מורשים לתשלומים (קוד שגיאה 111 אם לא)

סוגי אשראי (cred_type):

קודי מטבע:

תעודת זהות: חלק מהעסקאות דורשות פרמטר myid -- מספר תעודת זהות ישראלית בן 9 ספרות.

שלב 5: מימוש טוקניזציה לתשלומים חוזרים (הוראות קבע)

טוקנים מאפשרים לחייב לקוחות חוזרים בלי לטפל בנתוני כרטיס מחדש:

1. יצירת טוקן בתשלום הראשון:

• Iframe: התנהגות ברירת מחדל (מצב J5) מחזירה TranzilaTK
• API: השתמשו ב-tranmode=K (טוקן בלבד), VK (אימות + טוקן), או AK (חיוב + טוקן)

2. אחסון הטוקן בצורה מאובטחת:

• הטוקן הוא מחרוזת בת 19 תווים (4 הספרות האחרונות תואמות לכרטיס)
• שמרו טוקן, תאריך תפוגה, ו-4 ספרות אחרונות במסד הנתונים
• לטוקן אין ערך ללא אישורי המסוף שלכם

3. חיוב הטוקן מאוחר יותר:

• השתמשו בנקודת הקצה /cgi-bin/tranzila31tk.cgi
• כללו TranzilaTK, expdate, sum, ו-currency

שלב 6: הוספת 3D Secure (במידת הצורך)

3D Secure V2 מוסיף אימות בעל הכרטיס. עיינו ב-references/3ds-flow.md לזרימה המלאה. נקודות עיקריות:

• 3DS משנה את זרימת התשלום וכולל שלב אימות מול הבנק
• התגובה כוללת שדות נוספים לסטטוס האימות
• חלק מהמנפיקים הישראליים עשויים לא לתמוך ב-3DS לכל סוגי הכרטיסים

שלב 7: קבלת תשלומי Bit

טרנזילה תומכת ב-Bit (אפליקציית התשלום הנייד הפופולרית בישראל) דרך API ייעודי ל-Bit, לא דגל על ה-CGI של חיוב הכרטיס. יש לו endpoints משלו Bit - Init ו-Bit - Refund תחת https://api.tranzila.com/v1 עם אותו אימות HMAC של 4 כותרות כמו שאר API V2.

1. קראו ל-endpoint של Bit Init דרך ה-API -- טרנזילה מחזירה כתובת תשלום Bit 2. הפנו את הלקוח לכתובת ה-Bit או הציגו קוד QR 3. הלקוח מאשר תשלום באפליקציית Bit 4. טרנזילה שולחת את התוצאה ל-notify_url שלכם 5. החזרי Bit משתמשים ב-endpoint הייעודי של Bit Refund, לא בזרימת החזר הכרטיס

מגבלות Bit (מהתיעוד): שקלים בלבד, סכום העסקה מעל 5 ש"ח, והעוסק צריך מזהה של ויזה או ישראכרט, עוסקים עם מקס בלבד אינם מקבלים את השירות כרגע. Bit לא תומך ב-Hosted Fields או 3DS. אל תניחו פרמטרים bit=1 / bit_url על ה-CGI הישן; השתמשו ב-API הייעודי של Bit. ראו https://docs.tranzila.com/docs/payments-billing/dcljft4y7sgj2-bit.

שלב 8: יצירת קישורי תשלום (Payment Requests)

בקשות תשלום (TRAPI) מאפשרות לשלוח קישורי תשלום במייל או SMS ללא בניית דף checkout:

1. צרו בקשת תשלום דרך API עם סכום, תיאור, ופרטי קשר של הלקוח 2. טרנזילה מייצרת קישור תשלום מאובטח 3. שלחו את הקישור ללקוח (טרנזילה יכולה לשלוח אוטומטית במייל/SMS) 4. הלקוח לוחץ על הקישור ומשלם בדף מתארח של טרנזילה 5. מקבלים את התוצאה דרך webhook

זה שימושי לחשבוניות, הזמנות טלפוניות, או כל תרחיש שבו צריך לגבות תשלום ללא טופס מוטמע.

שלב 9: הגדרת הוראות קבע (תשלומים חוזרים)

לחיוב חוזר אוטומטי מעבר לחיוב טוקנים פשוט, טרנזילה מציעה הוראות קבע:

1. צרו הוראת קבע עם לוח תשלומים (סכום, תדירות, תאריכי התחלה/סיום) 2. טרנזילה מחייבת את הלקוח אוטומטית לפי הלוח 3. עקבו אחר תוצאות דרך Reports API או התראות webhook 4. בטלו או שנו הוראות קבע דרך API

הוראות קבע הן תכונה בתשלום -- פנו לטרנזילה להפעלה במסוף שלכם. ראו את חלק Standing Orders תחת https://docs.tranzila.com/.

שלב 10: הפקת חשבוניות

לטרנזילה API חשבוניות להפקת מסמכי מס חתומים דיגיטלית ומאושרים על ידי רשות המיסים:

1. צרו חשבוניות מקושרות לעסקאות או באופן עצמאי 2. החשבוניות חתומות דיגיטלית לעמידה בדרישות מס 3. תמיכה בחשבוניות מס, קבלות, וחשבוניות זיכוי 4. ניתן להפיק אוטומטית עם תשלומי PayPal

מספר הקצאה (allocation number) של רשות המסים, חובה לחשבוניות B2B מעל סף. מ-1.1.2025 רשות המסים דורשת מספר הקצאה מ-שע"ם לכל חשבונית מס B2B מעל הסף. לוח: 20,000 ש"ח (מ-ינואר 2025), 10,000 ש"ח מ-ינואר 2026, 5,000 ש"ח מ-יוני 2026. בלי מספר הקצאה הקונה לא יכול לקזז מע"מ תשומות. אם אתם מנפיקים חשבוניות דרך ה-Invoicing API של Tranzila, אמתו עם תמיכת Tranzila שבקשות מספר הקצאה מועברות לשע"ם עבור חשבוניות מעל הסף הנוכחי; אם לא, השתמשו בספק חשבוניות נפרד (Green Invoice, Morning) שמחובר לשע"ם, או בקשו מספרי הקצאה ישירות בפורטל רשות המסים.

ראו את חלק Invoices תחת https://docs.tranzila.com/ למדריך החשבוניות המלא.

שלב 11: טיפול בשגיאות

תבדקו את שדה Response בכל תוצאת עסקה. 000 פירושו אושר -- כל דבר אחר הוא דחייה או שגיאה.

חשוב: סטטוס ה-HTTP של קריאת API V2 הוא 200 גם בעסקה שנדחתה או נכשלה. ה-200 לא אומר הצלחה; קראו את שדה ה-Response / קוד התגובה בגוף לקבלת תוצאת ה-SHVA האמיתית. ויש שני מרחבי קודים נפרדים: קודי SHVA/מנפיק (מאות קודים, סירובי מנפיק במאות ה-300, שגיאות תשלומים במאות ה-400) ומערך קודי 3D Secure נפרד (900-930). אל תניחו קודים מ-Stripe או משערים אחרים.

כמה קודים מאומתים (אמתו את השאר מול references/error-codes.md ועמוד "Transaction Response Codes" הרשמי ב-docs.tranzila.com):

למדריך המלא (260+ קודי SHVA ומערך 3DS 900-930 נפרד), עיינו ב-references/error-codes.md ואמתו מול התיעוד הרשמי, אל תקודדו קודים מהזיכרון.

דוגמאות

דוגמה 1: קבלת תשלום חד-פעמי

המשתמש אומר: "אני צריך להוסיף תשלום בכרטיס אשראי לדף התשלום שלי ב-Node.js" פעולות: 1. בחירה: אינטגרציית Iframe (היקף PCI מינימלי) 2. הנחיה: הטמעת iframe עם שם מסוף, סכום, currency=1 (ש"ח) 3. מימוש: handler בצד השרת ל-notify_url לקליטת תגובה 4. אימות: בדיקת Response=000, שמירת ConfirmationCode תוצאה: דף תשלום עובד שמקבל כרטיסי אשראי ישראליים דרך טופס מוטמע.

דוגמה 2: הגדרת מנוי חודשי

המשתמש אומר: "אני רוצה לחייב לקוחות 99 ש"ח כל חודש אוטומטית" פעולות: 1. תשלום ראשון: Iframe עם יצירת טוקן (מצב J5) 2. שמירה: TranzilaTK ו-expdate מהתגובה 3. חודשי: cron job קורא ל-tranzila31tk.cgi עם הטוקן השמור 4. טיפול: בדיקת כרטיסים שפג תוקפם, טוקנים שנדחו תוצאה: חיוב חוזר חודשי באמצעות כרטיסים מטוקנים.

דוגמה 3: תשלום בתשלומים

המשתמש אומר: "הלקוח שלי רוצה לשלם 6,000 ש"ח ב-3 תשלומים" פעולות: 1. הגדרה: cred_type=8 (תשלומים) 2. חישוב: fpay=2000, spay=2000, npay=2 (3 תשלומים בסה"כ) 3. אימות: המסוף מורשה לתשלומים 4. עיבוד: עסקה עם פרמטרי תשלומים תוצאה: תשלום מחולק ל-3 תשלומים שווים של 2,000 ש"ח.

דוגמה 4: ביצוע החזר

המשתמש אומר: "אני צריך לבצע החזר לעסקה מהשבוע שעבר, קוד אישור 0283456" פעולות: 1. שימוש: tranmode=C0 (ביטול עסקה ראשונה באצווה) 2. כלול: ConfirmationCode ו-index המקוריים 3. הגדרה: sum לסכום ההחזר (חלקי או מלא) 4. אימות: Response=000 להחזר מוצלח תוצאה: החזר מעובד ומקושר לעסקה המקורית.

דוגמה 5: קבלת תשלום Bit

המשתמש אומר: "אני רוצה לאפשר ללקוחות לשלם עם Bit באתר שלי" פעולות: 1. קראו ל-endpoint הייעודי של Bit Init (api.tranzila.com/v1, אימות HMAC של 4 כותרות) -- לא דגל על ה-CGI של הכרטיס 2. הפניה: שלחו את הלקוח לכתובת התשלום של Bit מהתגובה (או הציגו QR) 3. טיפול: קבלו אישור תשלום ב-notify_url 4. אימות: תבדקו את קוד התגובה לתשלום Bit מוצלח 5. מגבלות: שקלים בלבד, סכום מעל 5 ש"ח, העוסק צריך מזהה ויזה/ישראכרט (עוסקי מקס בלבד אינם נתמכים) תוצאה: לקוחות יכולים לשלם באמצעות ארנק Bit לצד כרטיסי אשראי.

דוגמה 6: שליחת קישור תשלום ב-SMS

המשתמש אומר: "אני צריך לגבות תשלום מלקוח בטלפון" פעולות: 1. יצירה: בקשת תשלום דרך TRAPI עם סכום ומספר טלפון של הלקוח 2. שליחה: טרנזילה שולחת SMS עם קישור תשלום אוטומטית 3. המתנה: הלקוח פותח את הקישור ומשלם בדף המתארח של טרנזילה 4. אישור: קבלת התראת webhook כשהתשלום מושלם תוצאה: תשלום נגבה מרחוק ללא בניית דף checkout.

ספריות קהילתיות

• tranzilajs (TypeScript/Node.js) -- SDK מודרני עם HMAC auth, תשלומי Bit, פעולות כרטיס אשראי, יצירת iframe. התקנה: npm install tranzilajs. ראו: https://github.com/NirTatcher/tranzilajs
• omnipay-tranzila (PHP/Omnipay) -- תוסף gateway קהילתי
• active_merchant_tranzila (Ruby) -- מתאם gateway ל-ActiveMerchant

משאבים מצורפים

חומרי עזר

• references/api-parameters.md -- מדריך פרמטרים מלא של API טרנזילה לendpoints CGI ישנות ו-API V2, כולל כותרות אימות, פרמטרי עסקה, פעולות טוקן, ושדות תשלומים. עיינו בקובץ זה כשאתם בונים בקשות API או דיבוג פרמטרים.
• references/error-codes.md -- רשימה מלאה של קודי תגובה של טרנזילה (000-999) עם משמעויות וטיפול מומלץ. עיינו בקובץ זה כשעסקה מחזירה קוד שאינו 000.
• references/3ds-flow.md -- מדריך מימוש 3D Secure V2 שלב-אחר-שלב לטרנזילה, כולל זרימת redirect, פרמטרי אימות, וטיפול חלופי. עיינו בקובץ זה בעת הוספת 3DS לאינטגרציה קיימת.

סקריפטים

• scripts/validate_tranzila_response.py -- מאמת תגובת עסקה של טרנזילה: בודק קוד תגובה, מוודא נוכחות שדות נדרשים, ומסמן בעיות נפוצות (קוד אישור חסר, סכומים לא תואמים). הרצה: python scripts/validate_tranzila_response.py --help

מלכודות נפוצות

• ה-API של טרנזילה משתמש בזוגות מפתח-ערך בפורמט form-encoded (לא JSON). סוכנים ברירת מחדל לגוף בקשה JSON, שטרנזילה תדחה או תתעלם ממנו. תשלחו בקשות כ-application/x-www-form-urlencoded.
• מצב הבדיקות של טרנזילה משתמש באותו endpoint כמו ייצור אבל עם פרמטר supplier שונה. סוכנים עלולים בטעות לשלוח עסקאות בדיקה למסוף הייצור או להפך.
• פורמט התגובה מטרנזילה הוא מחרוזת טקסט פשוט של מפתח=ערך מופרדת בשורות חדשות, לא JSON. סוכנים עלולים לנסות JSON.parse() על התגובה, מה שיזרוק שגיאה.
• למספרי כרטיסי אשראי ישראליים טווחי BIN שונים מכרטיסים אמריקאיים/אירופיים. טרנזילה מאמתת כרטיסים מקומית, כך שכרטיסי בדיקה מ-Stripe או שערים בינלאומיים אחרים לא יעבדו.

קישורי עזר

פתרון בעיות

שגיאה: "העסקה נדחתה עם קוד תגובה שאינו 000"

סיבה: פרמטרים חסרים או לא תקינים, דחיית מנפיק, או בעיית הרשאה/הגדרה. זכרו שסטטוס ה-HTTP הוא 200 גם בכישלון, קראו את שדה ה-Response לקבלת הקוד האמיתי. פתרון: ודאו שכל הפרמטרים הנדרשים קיימים: supplier, TranzilaPW, sum, ccno (או TranzilaTK), expdate. תבדקו ששמות הפרמטרים מדויקים (case-sensitive). חפשו את קוד התגובה המדויק בעמוד הרשמי (ראו references/error-codes.md), אל תנחשו את משמעותו.

שגיאה: "מסוף לא מורשה לתשלומים / Amex"

סיבה: למסוף טרנזילה שלכם אין הרשאת תשלומים (או Amex). פתרון: פנו לתמיכת טרנזילה (073-222-4444) להפעלת תשלומים או Amex במסוף שלכם.

שגיאה: "חיוב טוקן נכשל אבל iframe עבד"

סיבה: נפוץ כשמשתמשים בendpoint שגויה או חסר expdate פתרון: חיובי טוקן משתמשים ב-/cgi-bin/tranzila31tk.cgi (לא tranzila31.cgi). כללו גם TranzilaTK וגם expdate.

שגיאה: "עסקה אושרה בבדיקה אבל לא בפרודקשן"

סיבה: מסופי בדיקה וייצור מתנהגים שונה פתרון: ודאו את שם המסוף והסיסמה בפרודקשן. חלק מהפעולות (כמו ביטול) מתנהגות שונה בפרודקשן. פנו לתמיכת טרנזילה אם ההתנהגות שונה.

שגיאה: "אי-התאמת מטבע"

סיבה: שימוש בendpoint שגויה למטבע פתרון: ש"ח ודולר משתמשים ב-tranzila31.cgi. רב-מטבעי (אירו, לירה שטרלינג ועוד) דורש tranzila36a.cgi.