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

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

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

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

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

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

עבור Iframe / Legacy CGI:

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

עבור API V2:

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

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

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

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

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

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

למדריך קודי השגיאה המלא (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 להחזר מוצלח תוצאה: החזר מעובד ומקושר לעסקה המקורית.

חומרי עזר

• 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.