מדריך מעשי ל-API של Hyp Pay, לשעבר YaadPay: איך APISign יוצר ומאמת דף תשלום, איך getToken ו-action=soft מחייבים כרטיס שמור, ומתי לתת ל-Hyp לנהל את החיוב החוזר עם HK=True.
עיקרי הדברים
- כל קריאה ל-Hyp Pay היא GET לכתובת https://pay.hyp.co.il/p/ עם Masof, KEY ו-PassP במחרוזת השאילתה, ולכן היא חייבת לרוץ בשרת שלכם.
- דף תשלום נחתם עם APISign What=SIGN, והפניית ההצלחה מאומתת עם APISign What=VERIFY, עם הפרמטרים באותו סדר.
- הטוקן לא מגיע בהפניה: getToken מחזיר Token בן 19 ספרות ו-Tokef, ושניהם נדרשים כדי לחייב עם action=soft.
- HK=True נותן ל-Hyp להריץ חיוב חוזר בסכום קבוע ומחזיר HKId; סכום משתנה או מחזור מותאם אומרים שאתם מריצים את לוח הזמנים בעצמכם.
ה-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: דף התשלום, טוקנים, חיוב חוזר וזיכויים.
איך נוצר דף תשלום ב-Hyp Pay?
דף תשלום ב-Hyp Pay נוצר בשרת שלכם, משולם בדפדפן של הלקוח ומאומת שוב בשרת. התהליך המתועד כולל חמישה שלבים:
- השרת שולח
action=APISign&What=SIGN&Sign=Trueיחד עםMasof,KEY,PassPופרמטרי התשלום. - Hyp מחזירה מחרוזת שאילתה: אותם פרמטרים,
actionשהשתנה ל-pay, ופרמטרsignatureשנוסף. את המחרוזת מצמידים כמו שהיא ל-https://pay.hyp.co.il/p/?, באותו סדר בדיוק. - הלקוח מופנה לכתובת הזו ומקליד את הכרטיס בדף של Hyp, כך שפרטי הכרטיס לא מגיעים לשרת שלכם.
- Hyp מפנה לכתובת ההצלחה שהוגדרה בפורטל של Hyp Pay, עם
Id,CCode,Amount,ACode,Order,Fild1עדFild3ו-Sign. - השרת שולח
action=APISign&What=VERIFYעם כל הפרמטרים שהגיעו בהפניה, באותו סדר.CCode=0פירושו שהעסקה תואמת את הרישום אצל Hyp.
Hyp מגדירה את השלב החמישי כרשות וממליצה לבצע אותו בכל עסקה. כדאי להתייחס אליו כחובה: ההפניה עוברת דרך הדפדפן של הלקוח, ושם אפשר לשנות אותה או שהיא פשוט לא תגיע. האימות גם תלוי ב-Sign=True בשלב הראשון ובהגדרה "אימות על ידי חתימה בעמודי התשלום" בפורטל, שלדברי Hyp פעילה בדרך כלל כברירת מחדל.
הפעולות של Hyp Pay שבאמת תשתמשו בהן
כל פעולה ב-Hyp Pay נשלחת לאותה כתובת, והפרמטר action קובע מה היא עושה. אלה הפעולות שחנות או עסק מנויים צריכים בדרך כלל:
| action | מה היא עושה | פרמטרים עיקריים | תשובה מוצלחת |
|---|---|---|---|
APISign + What=SIGN | יוצרת כתובת חתומה לדף תשלום | Masof, KEY, PassP, Sign=True, Amount, Coin, Tash, Order | מחרוזת עם action=pay ו-signature |
APISign + What=VERIFY | מוודאת שהפניית ההצלחה לא שונתה | פרטי הגישה וכל פרמטרי ההפניה, לפי הסדר | CCode=0 |
getToken | מחזירה את הטוקן של הכרטיס מעסקה | Masof, PassP, TransId, ו-allowFalse כרשות | Token (19 ספרות) ו-Tokef (YYMM) |
soft | חיוב שרת-לשרת, למשל של טוקן שמור | CC, Token=True, Tmonth, Tyear, UserId, ClientName, Info, Amount | Id, CCode=0, ACode |
HKStatus | עוצרת או מחדשת הסכם חיוב חוזר שמנוהל ב-Hyp | HKId, NewStat (1 עוצר, 2 מחדש) | HKId, CCode=0 |
zikoyAPI | זיכוי מלא או חלקי של עסקה שכבר שודרה | TransId, Amount | Id חדש, CCode=0 |
כמה ערכים שכדאי להכיר לפני הבקשה הראשונה: Coin הוא 1 לשקל (ברירת המחדל), 2 לדולר, 3 לאירו ו-4 לליש"ט; PageLang מקבל HEB או ENG; Tash הוא מספר התשלומים המקסימלי שהלקוח יכול לבחור. מספרי מסופי בדיקה מתחילים תמיד ב-00100, התיעוד מפרסם כרטיס בדיקה אחד להצלחה ואחד לכישלון, ובייצור משתמשים באותה כתובת עם פרטי הגישה של הייצור.
איך עובד חיוב חוזר ב-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 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 ויעד שריג הם אותו דבר?
כן, מבחינת שער הסליקה. תיעוד המפתחים של Hyp מתאר את Hyp Pay כמוצר שנקרא בעבר YaadPay, השער של יעד שריג. ל-Hyp יש גם את Hyp Enterprise, לשעבר Hyp CreditGuard, שהוא ממשק אחר. בררו לאיזה מהשניים שייך המסוף שלכם לפני שמתכננים את עבודת החיבור.
יש ל-Hyp Pay סביבת בדיקה?
כן. מספרי מסופי בדיקה של Hyp Pay מתחילים תמיד ב-00100, והתיעוד מפרסם כרטיס בדיקה אחד שמצליח ואחד שנכשל. הכתובת זהה בבדיקה ובייצור, https://pay.hyp.co.il/p/, ולכן מעבר לייצור פירושו החלפת Masof, KEY ו-PassP בערכי הייצור שמקבלים מ-Hyp. אחרי ההחלפה כרטיס הבדיקה כבר לא יעבוד.
איך מחייבים כרטיס שמור ב-Hyp Pay?
שומרים את ה-Id מהתשלום המוצלח הראשון, קוראים ל-action=getToken כשהוא נשלח כ-TransId, ושומרים את Token ו-Tokef שחוזרים. כדי לחייב שולחים action=soft עם CC שמכיל את הטוקן, Token=True, Tmonth ו-Tyear מתוך Tokef, UserId, ClientName, Info ו-Amount. CCode=0 בתשובה פירושו שהחיוב אושר, וכל ערך אחר הוא קוד דחייה או שגיאה.
איך עוצרים חיוב חוזר ב-Hyp?
בהסכם ש-Hyp מנהלת שולחים action=HKStatus עם Masof, PassP, ה-HKId שחזר בהפניית ההצלחה הראשונה ו-NewStat=1. הערך NewStat=2 מחדש הסכם שהופסק, וקוד 906 פירושו שההסכם לא קיים. אפשר גם לעצור את ההסכם ידנית מתוך חשבון Hyp Pay, ובכל מקרה כדאי לשמור את ה-HKId כבר ברגע התשלום הראשון.
אפשר לזכות חלק מעסקה ב-Hyp Pay?
כן. שולחים action=zikoyAPI עם Masof, PassP, ה-Id של העסקה המקורית בתור TransId, והסכום לזיכוי ב-Amount, עד גובה העסקה המקורית. זיכוי יוצר עסקה חדשה עם Id משלה. קוד 33 פירושו שהסכום שביקשתם גבוה ממה שהעסקה מאפשרת לזכות, ולכן כדאי לשמור בצד שלכם כמה כבר זוכה מכל עסקה.
להמשך קריאה
שירות רלוונטי
אינטגרציות
לגרום למערכות שאתם כבר משלמים עליהן לדבר זו עם זו.
על הכותב
יהונתן סעדיה
מפתח פרילנסר לאוטומציה, אתרים ו-MVP
אני יהונתן סעדיה, מפתח בכיר שבונה אוטומציה עסקית, אתרים מותאמים ומוצרי MVP לעסקים קטנים ובינוניים בארה"ב, אירופה וישראל. המדריכים האלה נכתבים מתוך עבודה אמיתית עם לקוחות, לא מתיאוריה.
בוא נעבוד יחדיש לך פרויקט דומה?
ספר לי מה אתה רוצה לבנות או איזה תהליך להפוך לאוטומטי. אני חוזר תוך 24 שעות עסקים עם כמה שאלות ממוקדות, ואז עוברים על זה יחד בשיחת היכרות חינמית של 30 דקות, בלי התחייבות. בסוף יש לך היקף עבודה, לוח זמנים ומחיר קבוע - או תשובה כנה שלא שווה לבנות את זה.