אינטגרציה מול טרנזילה: ה-iframe, ה-Handshake, ולמה הוא בכלל קיים

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

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

ה-iframe: הבסיס

כתובת הבסיס של ה-iframe נראית כך:

https://direct.tranzila.com/<terminalname>/iframenew.php

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

התיעוד הרשמי יושב ב-docs.tranzila.com, וכדאי לפתוח אותו: לטרנזילה יש כמה וריאציות של ממשק ה-iframe, והבחירה ביניהן משפיעה על מה שאתה בונה.

הבעיה: הסכום נמצא בידי הדפדפן

הנה התרחיש שכדאי להבין לפני שמחליטים לוותר על ה-Handshake.

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

התוצאה: המשתמש משלם 1 שקל על מוצר של 500. העסקה מאושרת אצל הסולק, כי מבחינתו זה הסכום שביקשו לחייב. השרת שלך מקבל הודעה על עסקה מוצלחת. אם אתה לא מצליב את הסכום, אתה שולח את המוצר.

זו לא מתקפה תיאורטית ולא דורשת מיומנות מיוחדת - היא דורשת דפדפן.

הפתרון: Handshake

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

הזרימה:

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

שינוי הסכום ב-DOM כבר לא משנה כלום, כי הערך הקובע נשמר בצד השרת מרגע ההנפקה.

שתי דרישות שכדאי לדעת מראש

1. נדרש מודול טוקנים בתשלום. ה-Handshake אינו זמין כברירת מחדל - הוא דורש רכישת מודול והפעלה על המסוף. זו דרישה מסחרית ולא שורת קוד. יש לוודא שהוא מופעל לפני שמתמחרים את העבודה ללקוח, אחרת אתה מגלה באמצע הפיתוח שהארכיטקטורה שתכננת דורשת החלטת רכש.

2. האימות אינו טריוויאלי. ה-Handshake בגרסה v2 עובד מול:

POST https://api.tranzila.com/v2/handshake/create

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

חלק מהפעולות דורשות גם את שם המסוף וגם את סיסמת המסוף. שניהם סודות בצד השרת.

מה עדיין חייב לקרות בצד שלך

גם עם Handshake, שלושה דברים נשארים באחריותך:

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

אל תסמוך על ההפניה בדפדפן

כמו בכל סולק: המסלול שבו הדפדפן חוזר לדף התודה שלך אינו אמין. לקוח שסוגר את הלשונית ברגע שהתשלום עבר לעולם לא יגיע לשם, וההזמנה תישאר "ממתינה" למרות שהכסף נגבה.

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

PCI וגבולות

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

צ'קליסט לפני העלייה לאוויר

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

להשוואה בין הסולקים הישראליים, ראה השוואת סולקים ישראליים למפתחים. לחיבור בין סליקה להפקת מסמכים, ראה השוואת ה-API של מערכות החשבוניות.