לזרימת התשלום של Grow יש שלב שרוב האינטגרציות מפספסות: אחרי הקולבק השרת שלך חייב לקרוא ל-approveTransaction. מה באמת עושים createPaymentProcess ו-approveTransaction, מה אי אפשר לבדוק ב-sandbox, ולמה תשלומים משנים לך את הרישום החשבונאי.
עיקרי הדברים
- השם השתנה. משולם היא כיום Grow, והתיעוד נמצא ב-developers.grow.business - חיפוש השם הישן מחזיר חומר ותיק שעשוי לא להתאים לממשק הנוכחי.
- הזרימה דו-שלבית: createPaymentProcess פותח את דף התשלום, ואחרי הקולבק השרת שלך קורא ל-approveTransaction. התיעוד של Grow מחייב את הקריאה השנייה כאישור קבלה ומציין שהעסקה מעובדת גם בלעדיה - היא לא מזיזה את הכסף, אבל דילוג עליה מוציא אותך מהדרישות של הספק.
- פריסה לתשלומים היא יכולת מרכזית בשוק הישראלי והיא משנה את הרישום החשבונאי. יש להחליט עם רואה החשבון אם המסמך משקף את הסכום המלא או את התשלום, לפני הבנייה.
- הקולבק הוא מקור האמת, לא הדפדפן. לקוח שסוגר את הלשונית אחרי התשלום לעולם לא חוזר לדף שלך, אבל השרת שלך עדיין שומע על זה.
הדבר הראשון שכדאי לדעת הוא ששם המוצר השתנה: משולם היא כיום Grow, והתיעוד למפתחים יושב ב-developers.grow.business, שאליו מפנה העמוד grow.business/api-developers. חיפוש "משולם API" עדיין מחזיר חומר, אבל חלקו ותיק ולא בהכרח תואם לממשק הנוכחי - שווה לפתוח את התיעוד הרשמי ולא להסתמך על דוגמה שמצאת.
הזרימה - וההבדל שמפיל אינטגרציות
הדפוס המרכזי הוא דו-שלבי, וזו הנקודה שהכי חשוב להבין:
createPaymentProcess- השרת שלך יוצר תהליך תשלום. מקבל בחזרה דף תשלום שאפשר להטמיע ב-iframe או להפנות אליו.- הלקוח משלם בדף של Grow. פרטי הכרטיס לא עוברים דרכך.
- Grow מודיעה לשרת שלך בקולבק.
approveTransaction- השרת שלך מאשר את העסקה.
השלב הרביעי הוא מה שרוב האנשים מפספסים. התיעוד של Grow קובע שחובה לקרוא ל-approveTransaction אחרי שמגיע עדכון שרת-לשרת, ומתאר את הקריאה כאישור של המערכת שלך שההודעה התקבלה ושמצב העסקה ידוע לה. באותו עמוד כתוב גם שהעסקה מעובדת גם אם הקריאה לא בוצעה או נכשלה - כלומר היא לא מה שמזיז את הכסף. אינטגרציה שמדלגת עליה עדיין נראית תקינה בבדיקות, אבל היא לא עומדת בדרישה של הספק, וזה מקום לא נוח להיות בו כשמגיעה מחלוקת או פנייה לתמיכה.
למה בכל זאת כדאי להתייחס לשלב השני כנקודת בקרה: זה הרגע הטבעי שבו השרת שלך מאמת, לפני שהוא מסמן משהו כמשולם - שהסכום נכון, שההזמנה קיימת, שהיא לא כבר שולמה. זו לא בירוקרטיה, זו נקודת בקרה, וכדאי להשתמש בה.
מה לעשות בין השלבים
ברגע שהקולבק מגיע ולפני approveTransaction:
- להצליב את הסכום מול ההזמנה בצד השרת. אם הוא לא תואם - לא לסמן את ההזמנה כמשולמת, ולהעביר לבדיקה.
- לבדוק שההזמנה לא כבר שולמה. קולבקים יכולים להגיע פעמיים.
- לתעד את התשובה המלאה לפני שממשיכים. אם משהו ייכשל בהמשך, זו הראיה.
אילו מזהים ה-API של Grow מבקש?
אינטגרציה ישירה מול Grow מזהה כל בקשת תשלום בשני ערכים ש-Grow מנפיקה בתהליך ההצטרפות: userId ו-pageCode. פלטפורמה שגובה עבור כמה עסקים מוסיפה apiKey, ושולחת את ה-userId של העסק שמקבל את הכסף ואת ה-pageCode של אמצעי התשלום. לכל סביבה יש סט ערכים משלה.
| ערך | מתי הוא נשלח | מה עושים איתו |
|---|---|---|
userId | בכל בקשה | סוד בצד השרת, אחד לכל סביבה |
pageCode | בכל בקשה, לפי אמצעי התשלום | הגדרה, לא קוד |
apiKey | רק במבנה של כמה עסקים | סוד בצד השרת |
processId, processToken | חוזרים ביצירת התהליך ושוב בקולבק | לשמור על ההזמנה; בקשות המשך על העסקה, כמו זיכוי, נשענות עליהם |
קישור התשלום עצמו קצר מועד: לפי התיעוד של Grow הכתובת בתוקף 10 דקות. יוצרים אותו כשהלקוח עומד לשלם, לא כשנפתחת טיוטת ההזמנה, ולא שולחים אותו כקישור "לתשלום מאוחר יותר".
איך נראה הקולבק של Grow?
הקולבק של Grow הוא בקשת POST ב-HTTPS לכתובת ה-notifyUrl שהעברת ביצירת התהליך. התיעוד מדגיש שהפרמטרים מגיעים באותה צורה שבה שלחת אותם לקריאת היצירה, לא כ-JSON - נקודת קצה שמפענחת רק גוף JSON תקרא בקשה ריקה ותפיל תשלום אמיתי.
השדות בדוגמה המתועדת שחשובים להתאמה:
transactionIdו-asmachta- מזהה העסקה אצל Grow ומספר האישור של הכרטיס.sum,paymentsNum,firstPaymentSum,periodicalPaymentSum- הסכום הכולל והחלוקה לתשלומים, שעליהם נשענת השאלה החשבונאית שבהמשך.statusCode,cardSuffix,cardBrand- לקבלה וליומן התמיכה.customFields- השדות המותאמים ששלחת (בדוגמה מופיעcField1), המקום הטבעי להעביר בו את מזהה ההזמנה.
כדי לבדוק את נקודת הקצה בלי לשלם, בסביבת הבדיקות יש קריאת updateMyUrl ששולחת קולבק לדוגמה לכתובת שנותנים לה.
האם יש ל-Grow סביבת בדיקות, ומה אי אפשר לבדוק בה?
כן. כתובת הבסיס של ה-sandbox של Grow היא https://sandbox.meshulam.co.il/api/light/server/1.0/ - השם הישן נשאר בכתובת - וסביבת הייצור נפתחת רק אחרי ש-Grow מאשרת שהפיתוח והבדיקות הסתיימו. כרטיסי הבדיקה המתועדים הם 4580458045804580 (לתשלום יחיד בלבד, ושימושי כדי לייצר כישלון בעסקה בתשלומים), 4580000000000000 ו-4580111111111121.
המלכודת היא אמצעי התשלום שאין להם סביבת בדיקות בכלל:
- ביט, Google Pay ו-Apple Pay - לפי Grow הם רצים כעסקאות אמיתיות שמחויבות, גם בזמן הפיתוח.
- PayBox - אי אפשר להשלים אותו ב-sandbox, והוא זמין רק בייצור.
- Apple Pay בתוך iframe - מחייב אימות דומיין מראש.
לכן כדאי לתכנן תשלום אמיתי קטן אחד לכל ארנק לפני העלייה לאוויר, ולהחליט מראש מי מזכה אותו.
קולבק או webhook: מה Grow שולחת?
שניהם קיימים, והם לא אותו דבר. הקולבק ל-notifyUrl שייך לתהליך תשלום שהשרת שלך יצר. ה-webhooks של Grow הם יכולת נפרדת שהתמיכה מפעילה בחשבון, עם אירועים שבוחרים: עסקאות חד-פעמיות מכל דף ומקור, קישורי תשלום מסוימים, מכירות מתוסף WordPress, חיובים חוזרים מהחיוב השני והלאה, חיוב חוזר שנכשל, תשלומים ממסופי POS, הפקת חשבונית ועסקאות מאפליקציית Grow. אם העסק מוכר גם דרך דף תשלום של Grow או דרך האפליקציה, רק webhook יספר למערכת שלך על המכירות האלה. במדריך ה-webhooks מופיע שדה webhookKey בתוכן ההודעה, אבל לא מתואר מנגנון חתימה, ולכן כדאי לאמת כל אירוע מול ההזמנה והסכום אצלך לפני שפועלים לפיו.
תשלומים - היכולת שמשנה את הרישום
פריסה לתשלומים (עד 12) היא יכולת מרכזית בשוק הישראלי, ובניגוד לרוב הפיצ'רים היא לא רק עניין של סליקה - היא עניין חשבונאי.
השאלה שצריך לשאול את רואה החשבון של העסק, לפני שכותבים קוד:
כשלקוח משלם ב-6 תשלומים, האם המסמך משקף את הסכום המלא במועד העסקה, או שכל תשלום מייצר רישום משלו?
לשתי הגישות יש היגיון, והתשובה תלויה בשיטת הדיווח של העסק. מה שלא לגיטימי הוא שהמפתח יחליט לבד - זו החלטה שקובעת מתי מוכרת ההכנסה.
ההשלכה המעשית: המערכת שלך צריכה לדעת גם את הסכום הכולל וגם את מספר התשלומים, ולשמור את שניהם. אם שמרת רק את מה שנגבה החודש, איבדת את ההקשר.
הקולבק הוא מקור האמת
כמו בכל סולק - קארדקום, טרנזילה, PayPlus - ההפניה בדפדפן אינה אמינה כמנגנון עדכון.
לקוח שסוגר את הלשונית ברגע שהתשלום עבר, שהאינטרנט שלו נופל, או שפשוט לא ממתין - לא יחזור לדף שלך. אם שם אתה מסמן את ההזמנה כמשולמת, היא תישאר "ממתינה" למרות שהכסף נגבה.
הכלל: הקולבק מעדכן את מצב ההזמנה ומפעיל את approveTransaction. הדפדפן מציג מסך תודה. אף פעם לא להפך.
ונקודת הקצה של הקולבק חייבת להיות אידמפוטנטית - אותה הודעה יכולה להגיע פעמיים, ואסור שזה יסמן שתי הזמנות משולמות או ישלח שני משלוחים.
מי מפיק את המסמך
ההחלטה שחוזרת בכל פרויקט שמחבר סליקה והנהלת חשבונות: אם הסולק מוגדר להפיק מסמך אוטומטית והמערכת שלך גם מפיקה דרך מערכת החשבוניות, נוצרים שני מסמכי מס על עסקה אחת.
זה מתגלה בסוף החודש, אצל רואה החשבון. לבחור צד אחד ולתעד אותו לפני שכותבים שורה.
אבטחה
- לא לגעת בפרטי כרטיס. הם מוזנים בדף של Grow. אל תעביר, אל תתעד, אל תשמור - אחרת אתה נכנס להיקף PCI DSS.
- לאמת את הקולבק. נקודת קצה ציבורית שמסמנת הזמנות כמשולמות ומפעילה אישור עסקה היא יעד מובן מאליו. אין להסתמך על סודיות הכתובת.
- סודות בצד השרת בלבד. פרטי הגישה מאפשרים גבייה בשם העסק - לא בקוד המקור, לא בלוגים, ולא בדפדפן.
צ'קליסט לפני העלייה לאוויר
- לפתוח את התיעוד ב-
developers.grow.business- לא לחפש "משולם", השם השתנה. - לוודא ש-
approveTransactionנקרא בכל מסלול מוצלח. זו הבדיקה שהכי מרבים לפספס. - לבדוק את התרחיש שבו הלקוח משלם וסוגר מיד את הלשונית - האם ההזמנה עודכנה?
- לבדוק קולבק כפול - האם ההזמנה סומנה פעמיים?
- לקבל מרואה החשבון בכתב איך נרשמת עסקה בתשלומים.
- לוודא שאין הפקת מסמך כפולה.
- לבדוק כישלון אמיתי, לא רק הצלחה.
להשוואה בין הסולקים הישראליים, ראה השוואת סולקים ישראליים למפתחים.
מקורות
שאלות נפוצות
האם משולם ו-Grow זה אותו דבר?
כן - משולם עברה מיתוג מחדש ל-Grow, והתיעוד למפתחים מפורסם ב-developers.grow.business. חיפוש השם הישן עדיין מחזיר תוצאות, אבל חלק מהחומר הזה קדם לממשק הנוכחי, ולכן כדאי לעבוד מהתיעוד הרשמי ולא מדוגמה ותיקה שמוצאים בפורום או בפוסט.
מה עושה approveTransaction בזרימה של Grow?
זה האישור של השרת שלך, אחרי שהקולבק מגיע, שההודעה התקבלה ושמצב העסקה ידוע לו. הזרימה היא createPaymentProcess, הלקוח משלם בדף של Grow, Grow קוראת חזרה לשרת שלך, ואז אתה קורא ל-approveTransaction. התיעוד של Grow מחייב את הקריאה, ומציין גם שהעסקה מעובדת אם היא לא בוצעה או נכשלה.
מה צריך לקרות בין הקולבק של Grow לאישור העסקה?
ולידציה. להצליב את הסכום מול ההזמנה בצד השרת ולא לסמן את ההזמנה כמשולמת אם הוא לא תואם, לוודא שההזמנה לא כבר שולמה כי קולבקים יכולים לחזור, ולתעד את התשובה המלאה לפני שממשיכים. התכנון הדו-שלבי קיים בדיוק כדי לתת לך את נקודת הבקרה הזו - כדאי להשתמש בה ולא לסמן הזמנות כמשולמות בעיוורון.
איך צריך לרשום תשלום בפריסה בהנהלת החשבונות?
זו החלטה של רואה החשבון של העסק, לא של המפתח. יש לשאול במפורש אם המסמך צריך לשקף את הסכום המלא במועד העסקה או שכל תשלום מייצר רישום משלו - לשתיהן יש היגיון, והתשובה תלויה בשיטת הדיווח של העסק. המערכת שלך חייבת לשמור גם את הסכום הכולל וגם את מספר התשלומים בכל מקרה, אחרת ההקשר אובד.
האם לעדכן סטטוס הזמנה בהפניה של Grow או בקולבק?
בקולבק. ההפניה בדפדפן תלויה בכך שהלקוח יישאר בדף, וכל מי שסוגר את הלשונית ברגע שהתשלום עובר לא חוזר - וההזמנה נשארת ממתינה בזמן שהכסף נגבה. יש להשתמש בקולבק לעדכון המצב ולהפעלת approveTransaction, להשאיר את ההפניה למסך תודה בלבד, ולהפוך את נקודת הקצה של הקולבק לאידמפוטנטית.
האם ל-API של Grow יש סביבת בדיקות?
כן. כתובת הבסיס של ה-sandbox היא https://sandbox.meshulam.co.il/api/light/server/1.0/, עם userId, pageCode ו-apiKey משלה, וכרטיסי בדיקה מתועדים כמו 4580458045804580. לביט, Google Pay ו-Apple Pay אין סביבת בדיקות והם מחויבים באמת, ו-PayBox עובד רק בייצור, ולכן כדאי לתכנן תשלום אמיתי קטן לכל אחד מהם.
האם הקולבק של Grow נשלח כ-JSON?
לא. Grow שולחת את הקולבק כבקשת POST ב-HTTPS לכתובת ה-notifyUrl, עם הפרמטרים באותה צורה שבה נשלחה קריאת היצירה, והתיעוד אומר במפורש שזה לא JSON. נקודת קצה שמפענחת רק גוף JSON רואה בקשה ריקה, ולכן צריך לקרוא שדות טופס כמו transactionId, sum, paymentsNum ו-processToken.
מה ההבדל בין הקולבק של Grow ל-webhooks של Grow?
הקולבק מדווח על תהליך תשלום שהשרת שלך יצר דרך ה-API. ה-webhooks מופעלים בחשבון על ידי התמיכה של Grow ומדווחים על אירועים שבוחרים, כולל מכירות מדפי תשלום של Grow, מקישורי תשלום, מתוסף WordPress, ממסופי POS ומהאפליקציה, חיובים חוזרים מהשני והלאה, חיובים חוזרים שנכשלו והפקת חשבוניות.
להמשך קריאה
שירות רלוונטי
אינטגרציה בין מערכות
לגרום למערכות שאתם כבר משלמים עליהן לדבר זו עם זו.
יש לך פרויקט דומה?
ספר לי מה אתה רוצה לבנות או איזה תהליך להפוך לאוטומטי. אני חוזר תוך 24 שעות עסקים עם כמה שאלות ממוקדות, ואז עוברים על זה יחד בשיחת היכרות חינמית של 30 דקות, בלי התחייבות. בסוף יש לך היקף עבודה, לוח זמנים ומחיר קבוע - או תשובה כנה שלא שווה לבנות את זה.