ה-API של Hyp Pay (לשעבר יעד שריג): דף תשלום, טוקנים וחיוב חוזר

ה-API של Hyp Pay, שנקרא בעבר YaadPay (יעד שריג), הוא אוסף בקשות GET לכתובת https://pay.hyp.co.il/p/, שנושאות במחרוזת השאילתה את מספר המסוף (Masof), מפתח ה-API (KEY) וסיסמת ה-API (PassP). השרת שלכם חותם על דף תשלום, הלקוח משלם בדף של Hyp, והשרת מאמת את התוצאה, שולף טוקן לכרטיס ומחייב אותו שוב בהמשך.

Hyp מפרסמת היום את תיעוד המפתחים שלה ב-developers.hyp.co.il, בחלוקה לשני מוצרים: Hyp Pay, לשעבר YaadPay, ו-Hyp Enterprise, לשעבר Hyp CreditGuard. כשכתבנו על יעד שריג ופלאקארד, התיעוד הזה לא היה נגיש לציבור. עכשיו הוא נגיש, והמדריך מתמקד בצד של Hyp Pay: דף התשלום, טוקנים, חיוב חוזר וזיכויים.

להתחיל עם ה-API של Hyp: פרטי גישה, מסוף בדיקה ותיעוד

לקריאה הראשונה ל-API של Hyp צריך שלושה ערכים מ-Hyp והגדרה אחת בפורטל. צוות ההקמה של Hyp (ipos@hyp.co.il) שולח במייל את מספרי המסופים ואת פרטי הכניסה לפורטל, מסוף אחד וחשבון פורטל אחד לכל סביבה. מפתח ה-API וסיסמת ה-API נמצאים אחר כך בפורטל עצמו, לא במייל.

Hyp ממליצה להגדיר רק כתובת הצלחה ולהשאיר את הצגת השגיאות בדף התשלום שלה: כשמוגדרת כתובת שגיאה, כל עסקה שאינה חיוב מיידי רגיל מופנית אליכם. בודקים בסכומים נמוכים, בסביבות 10 ש"ח לפי ההמלצה של Hyp. התיעוד מפרסם כרטיס בדיקה אחד שמצליח ואחד שנכשל, ובמעבר לייצור משתנים רק מספר המסוף, KEY ו-PassP. כרטיס הבדיקה מפסיק אז לעבוד.

התיעוד נמצא בכתובת developers.hyp.co.il. הדפים של Hyp Pay יושבים תחת /pay/, של Hyp Enterprise תחת /enterprise/, ושני דפי העיון שתפתחו הכי הרבה הם API Actions (כל ערכי action) ו-Status Codes (מה אומר כל CCode).

איך נוצר דף תשלום ב-Hyp Pay?

דף תשלום ב-Hyp Pay נוצר בשרת שלכם, משולם בדפדפן של הלקוח ומאומת שוב בשרת. התהליך המתועד כולל חמישה שלבים:

1. השרת שולח action=APISign&What=SIGN&Sign=True יחד עם Masof, KEY, PassP ופרמטרי התשלום.
2. Hyp מחזירה מחרוזת שאילתה: אותם פרמטרים, action שהשתנה ל-pay, ופרמטר signature שנוסף. את המחרוזת מצמידים כמו שהיא ל-https://pay.hyp.co.il/p/?, באותו סדר בדיוק.
3. הלקוח מופנה לכתובת הזו ומקליד את הכרטיס בדף של Hyp, כך שפרטי הכרטיס לא מגיעים לשרת שלכם.
4. Hyp מפנה לכתובת ההצלחה שהוגדרה בפורטל של Hyp Pay, עם Id, CCode, Amount, ACode, Order, Fild1 עד Fild3 ו-Sign.
5. השרת שולח action=APISign&What=VERIFY עם כל הפרמטרים שהגיעו בהפניה, באותו סדר. CCode=0 פירושו שהעסקה תואמת את הרישום אצל Hyp.

Hyp מגדירה את השלב החמישי כרשות וממליצה לבצע אותו בכל עסקה. כדאי להתייחס אליו כחובה: ההפניה עוברת דרך הדפדפן של הלקוח, ושם אפשר לשנות אותה או שהיא פשוט לא תגיע. האימות גם תלוי ב-Sign=True בשלב הראשון ובהגדרה "אימות על ידי חתימה בעמודי התשלום" בפורטל, שלדברי Hyp פעילה בדרך כלל כברירת מחדל.

הפעולות של Hyp Pay שבאמת תשתמשו בהן

כל פעולה ב-Hyp Pay נשלחת לאותה כתובת, והפרמטר action קובע מה היא עושה. אלה הפעולות שחנות או עסק מנויים צריכים בדרך כלל:

כמה ערכים שכדאי להכיר לפני הבקשה הראשונה: Coin הוא 1 לשקל (ברירת המחדל), 2 לדולר, 3 לאירו ו-4 לליש"ט; PageLang מקבל HEB או ENG; Tash הוא מספר התשלומים המקסימלי שהלקוח יכול לבחור.

איך עובד חיוב חוזר ב-Hyp Pay?

Hyp Pay תומכת בחיוב חוזר בשתי דרכים, והבחירה ביניהן תלויה בשאלה אם הסכום קבוע.

• ניהול בצד Hyp - מוסיפים HK=True לבקשת דף התשלום, עם Amount כסכום הקבוע, freq כמחזור החיוב בחודשים, Tash=999 להמשך ללא הגבלה (או מספר חיובים מוגדר), ו-OnlyOnApprove=True כדי שההסכם ייכנס לתוקף רק אחרי שהתשלום הראשון אושר. TashFirstPayment קובע סכום שונה לחיוב הראשון. בהפניית ההצלחה מתווסף HKId, ששומרים כדי לעצור את ההסכם בהמשך עם HKStatus. Hyp מריצה את לוח הזמנים, ולכן זה מתאים למנויים.
• ניהול בצד שלכם - להסכמים פתוחים שבהם הסכום משתנה בכל פעם (בתיעוד זה נקרא הוראת קבע), או למחזורים כמו פעם בשבועיים. שומרים את ה-Id של העסקה הראשונה, שולפים טוקן, מריצים את לוח הזמנים בשרת שלכם ומחייבים כל מחזור עם action=soft.

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

חיוב טוקן שמור עם action=soft

טוקן של Hyp Pay הוא מספר בן 19 ספרות, שארבע הספרות האחרונות שלו זהות לאלה של הכרטיס, והוא ייחודי לכל בית עסק. הטוקן מייצג רק את מספר הכרטיס, ולכן צריך לשמור לצידו את תוקף הכרטיס. הטוקן לא מגיע בהפניית ההצלחה: מבקשים אותו עם action=getToken, כשה-Id מההפניה נשלח כ-TransId, והתשובה כוללת Token ו-Tokef.

החיוב עצמו הוא בקשת action=soft שבה CC מכיל את הטוקן, Token=True, Tmonth ו-Tyear נלקחים מ-Tokef, ו-UserId מכיל את מספר ת"ז מהתשלום הראשון, או 000000000 אם המסוף שלכם לא דורש ת"ז. התיעוד של Hyp מציין שמספר ת"ז הוא מידע אישי רגיש, ולכן שומרים אותו רק כשהמסוף דורש אותו. טוקן עובד במסוף שיצר אותו; מסוף נוסף תחת אותו מספר עוסק יכול להשתמש בו דרך tOwner.

שגיאות של getToken שכדאי לטפל בהן במפורש:

• 901 - למסוף אין הרשאה להשתמש בטוקנים.
• 902 - האימות נכשל, בדרך כלל בגלל PassP שגוי.
• 910 - העסקה לא הצליחה ולא נשלח allowFalse=True.

חיוב soft שנדחה מחזיר CCode שונה מ-0. מה עושים איתו במחזור הבא מוסבר במדריך הטיפול בחיובים חוזרים שנכשלו.

הפקת חשבונית יחד עם החיוב ב-Hyp Pay

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

• SendHesh=True שולח את המסמך ללקוח במייל, לכתובת שב-email.
• sendHeshSMS=True שולח קישור למסמך ב-SMS, למספר שב-cell.
• heshDesc הוא התיאור הכללי שמודפס בתא הפרטים.
• Pritim=True מודיע ל-Hyp שנשלחת רשימת פריטים; Hyp מכפילה כמות במחיר לכל פריט ומסכמת.
• EZ.customer_crn הוא מספר העוסק של הלקוח. לפי התיעוד של Hyp, החוק בישראל מחייב אותו במסמכים מעל 5,000 ש"ח.

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

Hyp Pay או Hyp Enterprise?

Hyp Pay ו-Hyp Enterprise הם שני ממשקים שונים, ולכן השלב הראשון הוא לברר לאיזה מהם שייך המסוף של העסק. Hyp Pay הוא מוצר השירות העצמי, והוא תומך ברמת ה-PCI הפשוטה ביותר, SAQ A. ל-Hyp Enterprise, לשעבר Hyp CreditGuard, יש תיעוד API נפרד עם פעולות כמו doDeal, refundDeal ו-inquireTransactions, עמוד webhooks מתועד, ותמיכה ב-SAQ A-EP וב-SAQ D. באינדקס התיעוד של Hyp Pay אין עמוד webhooks, ולכן ב-Hyp Pay הפניית ההצלחה יחד עם VERIFY היא האות שעליו בונים.

קוד שירשתם עשוי לפנות לכתובת הוותיקה icom.yaad.net ולא ל-pay.hyp.co.il. לפני שמשנים אותו, בררו מול Hyp איזו כתובת ואילו פרטי גישה תקפים למסוף שלכם. להשוואה עם המודל של שער סליקה ישראלי אחר, ראו את המדריך ל-API של קארדקום.

מה משתבש בחיבור ל-Hyp Pay

• פרטי גישה בדפדפן. KEY ו-PassP עוברים ב-URL, ולכן Hyp דורשת שהקריאות ייצאו מהשרת שלכם ב-TLS 1.2 ומעלה, וממליצה להסתיר את שניהם בלוגים.
• סדר פרמטרים שהשתנה. גם כתובת דף התשלום וגם קריאת VERIFY מצפות לפרמטרים בדיוק כפי שהתקבלו. בנייה מחדש מתוך אובייקט מפוענח עלולה לשנות את הסדר.
• אישורים שנקראים ככישלון. אם הגדרתם כתובת שגיאה, עסקת אישור בשני שלבים (700, J5) ועסקה דחויה (800) יופנו אליה, ולפי Hyp צריך להתייחס לשתיהן כהצלחה.
• טוקן בלי תוקף. בלי Tokef אי אפשר למלא את Tmonth ו-Tyear, והטוקן השמור חסר תועלת.
• בדיקת סטטוס HTTP במקום CCode. התוצאה נמצאת בגוף התשובה; 999 היא שגיאת תקשורת, ו-33 זיכוי גבוה מהמותר.
• אין הזמנה פנימית לפני APISign. צרו קודם רשומת הזמנה משלכם והעבירו אותה כ-Order, כך שהפניה שלא הגיעה תופיע כהזמנה שלא שולמה ואפשר יהיה לבדוק אותה בפורטל.

מקורות

• Hyp Pay - יצירת דף תשלום
• Hyp Pay - ניהול חיובים חוזרים
• Hyp Pay - שמירת טוקנים לכרטיס
• Hyp Pay - דרישות והגדרה ראשונית
• Hyp Pay - בדיקות וסביבות
• Hyp Pay - הפקת חשבוניות