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

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

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

דפוס	תיאור	היקף PCI	מתאים ל-
Iframe	דף תשלום מתארח בטרנזילה	מינימלי (SAQ-A)	אינטגרציה מהירה, עמידה מינימלית בתקנות
Hosted Fields	שדות קלט מתארחים בטרנזילה	נמוך (SAQ-A-EP)	חווית checkout מותאמת עם PCI נמוך
API V2 (שרת-לשרת)	תקשורת ישירה מול API	מלא (SAQ-D)	חיוב טוקנים, תשלומים חוזרים, החזרים

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

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

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

עבור Iframe / Legacy CGI:

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

עבור API V2:

• כותרת HTTP X-tranzila-api-app-key -- מפתח אפליקציה מלוח הבקרה של טרנזילה

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

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

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

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

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

זה נותן שליטה מלאה בעיצוב תוך שמירה על עמידה ב-SAQ-A-EP PCI. ראו https://docs.tranzila.com/docs/payments-billing/o033w842qo397-hosted-fields.

אפשרות ב: אינטגרציית 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):

ערך	סוג	תיאור
1	אשראי רגיל	חיוב רגיל לכרטיס אשראי
2	ויזה עדיף / אמקס אשראי
3	חיוב מיידי	חיוב ישיר מהחשבון
5	לאומי מיוחד
8	תשלומים	חלוקה למספר תשלומים
9	תשלומי מועדון	תשלומים במסגרת מועדון

קודי מטבע:

קוד	מטבע	תיאור
1	שקל חדש (ILS)	מטבע ברירת מחדל
2	דולר (USD)
3	לירה שטרלינג (GBP)
7	אירו (EUR)

תעודת זהות: חלק מהעסקאות דורשות פרמטר 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 (אפליקציית התשלום הנייד הפופולרית בישראל). הזרימה שונה מתשלום בכרטיס:

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

פרמטרים עיקריים: bit=1 להפעלת Bit, התגובה כוללת bit_url להפניית הלקוח. ראו 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

הוראות קבע הן תכונה בתשלום -- פנו לטרנזילה להפעלה במסוף שלכם. ראו https://docs.tranzila.com/docs/payments-billing/7lwf8jetxm6oq-create-a-standing-order.

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

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

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

ראו https://docs.tranzila.com/docs/invoices/e6843c7e8bc43-invoices-api למדריך החשבוניות המלא.

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

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

שגיאות נפוצות לטיפול בקוד:

קוד	משמעות	פעולה מומלצת
004	כרטיס סורב	בקשו מהמשתמש לנסות כרטיס אחר
036	כרטיס פג תוקף	בקשו מהמשתמש לעדכן פרטי כרטיס
107	סכום חורג מהמגבלה	הפחיתו סכום או פנו לבנק
111	מסוף לא מורשה לתשלומים	פנו לטרנזילה להפעלה
125	מסוף לא מורשה ל-Amex	פנו לטרנזילה להפעלה
200	שגיאת אפליקציה	נסו שוב; אם נמשך, בדקו פרמטרים
900	אימות 3DS נכשל	נסו ללא 3DS או בקשו מהמשתמש לאמת

למדריך קודי השגיאה המלא (170+ קודים), עיינו ב-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. הפעלה: הגדירו bit=1 בבקשת התשלום
2. הפניה: שלחו את הלקוח ל-bit_url מהתגובה
3. טיפול: קבלו אישור תשלום ב-notify_url
4. אימות: בדקו Response=000 לתשלום Bit מוצלח תוצאה: לקוחות יכולים לשלם באמצעות ארנק 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 טרנזילה לנקודות קצה 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

שגיאה: "Response code 200 -- Application error"

סיבה: פרמטרים חסרים או לא תקינים בבקשת ה-API פתרון: ודאו שכל הפרמטרים הנדרשים קיימים: supplier, TranzilaPW, sum, ccno (או TranzilaTK), expdate. בדקו ששמות הפרמטרים מדויקים (case-sensitive).

שגיאה: "Response code 111 -- Terminal not authorized for installments"

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

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

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

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

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

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

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