מדוע אינטגרציה של שערי תשלום ב-Medusa.js נשברת בפרודקשן
אינטגרציה של שערי תשלום ב-Medusa.js כמעט תמיד עוברת חלק בסביבת בדיקות ונשברת בפרודקשן — מכיוון שספק הבדיקות מגיב באופן מיידי ולעולם אינו חוזר על בקשות.
במציאות, וובהוקים של תשלומים מגיעים שוב, באיחור, לעיתים שלא לפי הסדר, והספק עשוי לשלוח אירוע על הצלחה כבר לאחר שההזמנה בוטלה עקב פסק זמן.
Medusa.js שומרת את סטטוס ההזמנה בנפרד מהעסקה של ספק התשלום, ואם לקשר ביניהם "בעין" — לפי זמן או לפי סכום — מקבלים אי-סנכרון של סטטוסי ההזמנה: הלקוח רואה "שולם", אך במערכת ההזמנה תלויה כלא משולמת, או להפך.
הכשל הטיפוסי השני — כפילויות חיובים. הספק אינו מבטיח מסירה חד-פעמית של הוובהוק: בעת תקלת רשת הוא יחזור על האירוע, ובלי אידמפוטנטיות של התשלום המטפל יבצע את התשלום פעמיים.
זה מטופל לא ב"בדיקה בקוד", אלא במפתח אידמפוטנטיות בצד הספק יחד עם יומן אירועים מעובדים במסד הנתונים של Medusa: וובהוק חוזר עם אותו מזהה חייב להיות מזוהה ולהתעלם ממנו לפני כל לוגיקה עסקית.
הכשל השלישי — אובדן תשלום בעת פסק זמן. המשתמש עבר לעמוד הספק, שילם, אך ההפניה לא חזרה — וההזמנה נשארת במצב תלוי, אף שהכסף חויב. כאן עובד רק התאמה אסינכרונית: תהליך רקע periodically מתשאל את הספק לגבי עסקאות "תקועות" ומביא את הסטטוס לסטטוס סופי, ולא מסתמך על חזרת הדפדפן.
כל שלושת הכשלים — על דבר אחד: זרם האירועים מהספק ומצב ההזמנה ב-Medusa.js חייבים להתכנס באופן דטרמיניסטי, ולא "בדרך כלל עובד". מפרקים כיצד זה נסגר ברמת הארכיטקטורה, ולא בטלאים במטפל.
מה נותן קונטור תשלומים שנבנה נכון
קונטור תשלומים שנבנה נכון ב-Medusa.js הוא לא "לחבר ספק ולשכוח", אלא שכבה מנוהלת בין ההזמנה, הספק והמחסן.
כאשר הוא בנוי כראוי, שיעור התשלומים המוצלחים מפסיק להיות תלוי בגחמות של שער אחד: ניתוב לפי סוג כרטיס ואזור שולח את התשלום למקום שבו הוא יעבור בניסיון הראשון, ולא למקום שמוגדר כברירת מחדל.
עמידות בפני כשל של ספק מונחת ברמת עיבוד הוובהוקים. אנחנו מבצעים עיבוד אידמפוטנטי של אירועים עם מפתח לפי מזהה תשלום ויומן מצבים — וובהוק חוזר מהספק לא יוצר הזמנה שנייה ולא מחייב את הכסף פעמיים.
זה מבטל סוג שלם של חיובים כפולים, שבגללם בדרך כלל מגיעים לברר: הלקוח רואה שני הולדים, התמיכה מאמתת דפי חשבון ידנית, והכסף חוזר אחרי ימים.
מהירות החזר הכספים היא תוצאה ישירה של אותו יומן. ביטול והחזר מאותחלים מהאדמין בפעולה אחת, הסטטוס מסונכרן עם הספק אוטומטית, ופערים נכנסים לדוח במקום לצוף בתלונות. התגובה לכשל של ספק מצטמצמת למעבר למסלול חלופי בלי לעצור מכירות.
אפשר לבדוק את הקונטור לפי כמה סימנים: שיעור התשלומים המוצלחים נשמר ברמה יציבה בלי תיקונים ידניים, וובהוקים חוזרים לא שוברים הזמנות, החזר עובר בצורה צפויה, וכשל של ספק אחד לא מפיל את השלמת ההזמנה כולה. אם לפחות סעיף אחד לא מתקיים — הקונטור בנוי חלקית, וזה נראה בעומס על התמיכה.
דרכי חיבור תשלומים: מה לבחור בהתאם למשימה
ב-Medusa.js ספק תשלומים הוא מודול עם סט קבוע של מתודות: אתחול תשלום, הרשאה, אישור (capture), החזר וטיפול בהתראות מהבנק. את דרך החיבור בוחרים לא לפי נוחות האינטגרציה, אלא לפי המידה שבה לוגיקת העסק של התשלום שונה מתרחיש טיפוסי של «סל → תשלום → הזמנה».
אם התרחיש סטנדרטי, סביר יותר לקחת מודול ספק מוכן: הוא כבר מכסה החזקת סכום (holding), החזר חלקי והרשאה מחדש, והעדכונים מגיעים יחד עם הליבה.
מודול ספק עצמאי מוצדק כאשר נדרשים שלבים לא סטנדרטיים — תשלום בחלקים, פיצולים רב-מטבעיים, קישור כרטיס לחשבון ללא חיוב, כללי ניסיונות חוזרים (retries) משל עצמך.
שכבת תשלומים חיצונית (שירות עצמאי בין החנות לבנק) מוסיפה חוליה נוספת, אך מבודדת את החנות מהחלפת סולק (acquiring): הספק מוחלף במקום אחד, הוויטרינה ולוגיקת ההזמנות לא נגעות.
| אפשרות | מתי מתאימה | מגבלות |
|---|---|---|
| מודול ספק מוכן | תרחיש תשלום טיפוסי, סולק אחד-שניים, נדרש אתחול מהיר | הלוגיקה מוגבלת למתודות המודול; שלבים לא סטנדרטיים יצטרכו לעקוף מבחוץ |
| מודול ספק עצמאי | תרחישים לא סטנדרטיים: פיצולים, חיובים חלקיים, קישור כרטיסים, ניסיונות חוזרים משל עצמך | הפיתוח והתמיכה בצד שלנו; בעדכוני ליבה משמעותיים יש לבדוק את המודול |
| שכבת תשלומים חיצונית | מספר סולקים, החלפת ספק תכופה, כללים אחידים למספר ויטרינות | חוליה נוספת בשרשרת התשלום; נדרשים ניטור וטיפול בפערים בסטטוסים |
בפועל, הבחירה כמעט תמיד תלויה בכמה תרחישי תשלום חיים יותר משנה. אם אחד — לוקחים מודול מוכן ולא מרבים בישויות. אם התשלום הופך לחלק מהמוצר, מחשבים את עלות הבעלות של מודול עצמאי מול שכבת ביניים: הראשון זול יותר באתחול, השנייה — בתפעול בעת החלפת סולק.
ננתח את סכימת התשלום שלכם ונציע דרך חיבור עם הערכה לפי לוחות זמנים ותמיכה.
שלבי הטמעת שער תשלומים ב-Medusa.js
העבודה מתחילה מביקורת של מערך התשלומים הקיים, ולא מהתקנת מודול: תחילה אנו מתעדים כיצד הזמנות, עגלות וסטטוסי תשלום מתנהלים במימוש ה-Medusa.js שלכם, אילו ספקים כבר מחוברים והיכן נשבר הקשר בין התשלום לשינוי סטטוס ההזמנה. לאחר מכן — רצף שבו כל שלב נשען על התוצאה של השלב הקודם.
כיצד בנוי התהליך
- ביקורת מערך התשלומים. מפרקים את מודולי התשלום הקיימים, את סכימת ההזמנות והעגלות, את הטיפול בהחזרים ובתשלומים חלקיים. בפלט — מפה של המקומות שבהם סטטוס ההזמנה אינו תואם את מצב התשלום בפועל.
- בחירה וחיבור ספק. קובעים האם האינטגרציה מתבצעת דרך מודול מוכן או דרך שירות תשלום עצמאי, ומגדירים אותו לתרחיש שלכם: תשלום חד-שלבי, תפיסת כספים בנפרד מהרשאה, חיובים חוזרים.
- הגדרת Webhooks. מגדירים קליטת התראות מהשער, אימות חתימה ועיבוד אידמפוטנטי של אירועים — Webhook חוזר לא אמור ליצור תשלום שני או לשכפל הזמנה.
- בדיקת תרחישי תשלום. מריצים תשלום מוצלח, סירוב, ביטול, החזר מלא וחלקי, תשלום עם עיכוב אישור. כל תרחיש מאמתים לפי סטטוס ההזמנה ולפי הרשומה ביומן התשלומים.
- טיפול בתקלות. מגדירים התנהגות בעת אי-זמינות השער: תור ניסיונות חוזרים, סטטוס ברור ללקוח, היעדר הזמנות "תקועות" במצב ביניים.
- סביבות בדיקה ועבודה. מריצים את כל מערך התרחישים במצב הבדיקה של הספק, לאחר מכן מחליפים למפתחות עבודה ובודקים את הפעולות הממשיות הראשונות תחת השגחה.
- מסירת נהלים. מוסרים תיעוד תצורה, סכימת מעבר התשלום והוראות לפעולה בעת תקלה — כדי שהתמיכה תסגור אירועים בלעדינו.
סדר השלבים אינו משתנה: הגדרת Webhooks ללא ביקורת מובילה לכפילויות בתשלומים, ובדיקת תרחישים ללא סביבת בדיקה מעבירה שגיאות לכסף אמיתי. אם כבר יש לכם אינטגרציה שעובדת חלקית — נתחיל בביקורת ונראה אילו שלבים יש לעשות מחדש ואילו אפשר להשאיר.
מה הלקוח מקבל לידיו לאחר ההטמעה
לאחר ההטמעה נשאר לצוות לא "קוד עובד אצלנו על המחשב הנייד", אלא מארז של ארטיפקטים שלפיו ניתן לפתח ולתחזק את התשלומים בלעדינו. כל סעיף הוא מה שבאמת מועבר למאגר הקוד ולתיעוד הפנימי של הלקוח.
- תצורת ספקים — מודולי תשלומים ב-Medusa.js עם פרופילים נפרדים לסביבת בדיקות ולסביבת עבודה, מפתחות רק דרך משתני סביבה, החלפת ספק ללא שינויים בלוגיקה העסקית.
- תרשים זרימות התשלום — דיאגרמות לכל תרחיש: תשלום רגיל, אישור, החזר חלקי, ביטול וניסיון חוזר. ניתן לראות היכן נוצרת העגלה, היכן נרשמת ההזמנה ובאיזה רגע ההזמנה נחשבת למשולמת.
- מדיניות טיפול ב-Webhooks — כללים מתועדים לקבלת אירועים מהשער: אימות חתימה, אידמפוטנטיות לפי מזהה האירוע, סדר הטיפול במשלוחים חוזרים, התנהגות כאשר השירות אינו זמין ותור להשלמת התראות שהוחמצו.
- טיפול בכשלים ובפסקי זמן — תרחישים שבהם השער לא הגיב או החזיר שגיאה: ניסיונות חוזרים עם השהיה, רישום סטטוס "בטיפול", אישור ידני ולוג ברור לניתוח התקרית.
- תיעוד התשלומים — נוהל הוספת ספק חדש, תיאור שדות התצורה, מטריצת סטטוסים של ההזמנה והוראות לתמיכה: מה לבדוק כאשר יש אי-התאמה בסטטוס בין השער למערכת.
- נוהל התאמות — סדר השוואת תנועות השער להזמנות, תדירות הבדיקה ורשימת האותות שלפיהם מופעל ניתוח אי-ההתאמות.
- הרשאות ותפקידים — הפרדת זכויות לגישה למפתחות ולהגדרות התשלומים, נוהל רוטציה של סודות והעברת גישה בעת החלפת האחראי.
מארז זה מספיק כדי לחבר ספק חדש או לנתח תנועה שנויה במחלוקת בכוחות הצוות הפנימי, מבלי לחזור למחברי האינטגרציה.
מקרה בוחן: כיצד ביטלנו חיובים כפולים והעלינו את שיעור התשלומים המוצלחים
הלקוח — שירות מנויים המבוסס על Medusa.js — הגיע עם בעיית צמיחה קלאסית: שיעור התשלומים המוצלחים עמד על 71%, וכל פנייה שלישית לתמיכה עסקה ב«הכסף חויב, אך ההזמנה לא נוצרה».
הסיבה התבררה לא כשער אחד, אלא בארכיטקטורה: אישור התשלום עובד באופן סינכרוני בבקשת המשתמש, ובמקרה של פסק זמן בתשובת הספק הלקוח חזר על הבקשה — ומכאן החיובים הכפולים.
מה שינינו
הפרדנו את זרימת התשלום לשני מעגלים בלתי תלויים. אתחול התשלום כעת רק יוצר רשומה עם סטטוס «ממתין» ומחזיר מזהה פעולה, בעוד שהסטטוס הסופי מגיע בהתראה נפרדת מהספק ומעובד באופן אידמפוטנטי — חזרה על אותו אירוע אינה יוצרת חיוב שני.
מפתח האידמפוטנטיות הוא מזהה הפעולה של הספק, ולא סשן המשתמש, ולכן ניסיונות חוזרים מצד הלקוח ו-webhooks חוזרים מתמזגים לכדי תנועה אחת.
המעגל השני — התאמה. אחת לכמה דקות תהליך רקע מתאים פעולות «תקועות» מול הסטטוס אצל הספק ומביא אותן למצב סופי, אם ההתראה אבדה. זה ביטל סוג של תקלות שבהן התשלום עבר, אך ההזמנה נותרה ללא יצירה.
מדדים לפני ואחרי
| מדד | לפני | אחרי |
|---|---|---|
| שיעור התשלומים המוצלחים | 71% | 96% |
| פניות לתמיכה בנושא תשלומים | ~40 בשבוע | בודדות |
| זמן תגובה לתקלת ספק | טיפול ידני, שעות | השלמה אוטומטית, דקות |
| חיובים כפולים | קבועים | בוטלו |
בנפרד הגדרנו ניתוב: כאשר השער הראשי אינו זמין, התעבורה עוברת לגיבוי, ולא מפילה את יצירת ההזמנה. זמן התגובה לתקלת ספק הצטמצם מטיפול ידני להשלמה אוטומטית של הפעולה — המהנדס מתערב רק באנומליות שההתאמה לא הצליחה לסגור בעצמה.
במה שונה עיבוד אידמפוטנטי של וובהוקים מחיוב חוזר
שער תשלומים מעביר וובהוק לפי עיקרון "עד לקבלת אישור" — בעת timeout, שגיאת רשת או אתחול מחדש של השירות, אותה התראה בדיוק מגיעה שוב. זוהי התנהגות תקנית, ולא תקלה: השער אינו יודע אם עיבדתם את האירוע או לא, ולכן חוזר על המשלוח.
משלוח חוזר של וובהוק וחיוב חוזר הם אירועים שונים. הראשון משמעותו שהתראה על תשלום שכבר עבר הגיעה בפעם השנייה; השני — שמהלקוח באמת חויבו כספים פעם נוספת. ערבוב המושגים הללו בקוד הוא שמוליד הזמנות כפולות, כפילויות של מיילים וחיובים חוזרים.
עיבוד אידמפוטנטי הוא תכונה של המטפל, שבה קריאה חוזרת עם אותו מזהה אירוע אינה משנה את מצב המערכת. בארכיטקטורת עיבוד תשלומים, מפתח האידמפוטנטיות הוא מזהה האירוע מהשער, ולא מספר ההזמנה: הזמנה אחת יכולה להוליד כמה אירועים לגיטימיים (אישור, קונפירמציה, החזר).
המטפל, בטרנזקציה אחת, בודק אם האירוע כבר נרשם קודם, ורק לאחר מכן משנה את סטטוס ההזמנה ומפעיל פעולות לוואי.
מסקנה מעשית עבור Medusa.js: מטפל הוובהוק חייב להיות אטומי ולהסתמך על אינדקס ייחודי לפי מזהה האירוע במסד הנתונים. אז משלוח חוזר פשוט יחזיר "כבר עובד" ולא יגע בהזמנה, וחיוב חוזר יהפוך לבלתי אפשרי ברמת סכימת הנתונים, ולא ברמת הבדיקות בקוד.
בנפרד אנחנו מקבעים את סדר האירועים: התראות יכולות להגיע שלא לפי הסדר, ולכן מעדכנים את סטטוס ההזמנה לפי כללי מעבר, ולא "כפי שהגיע".
אם שכבה זו אינה קיימת, ההגנה נבנית על התאמות ידניות וטיפול בפניות — וכל משלוח חוזר הופך לאירוע פוטנציאלי. אנחנו מתכננים את העיבוד כך שחזרה תהפוך לבטוחה כברירת מחדל: ייחודיות האירוע, טרנזקציה אטומית, יומן התראות מעובדות ומעברי סטטוס תקינים.
ספקות טכניים נפוצים לגבי אינטגרציית תשלומים
אינטגרציית תשלומים לעיתים רחוקות היא "התקנתי ושכחתי": ספקים משנים דרישות, מופיעים אמצעי תשלום חדשים, והעסק מבקש החזרים וחיובים חוזרים. להלן — ספקות טכניים שעולים לרוב בשיחות, וכיצד אנו פותרים אותם בקוד.
עד כמה קשה להחליף ספק תשלומים אם האינטגרציה כבר עובדת?
שכבת התשלומים ב-Medusa.js מבודדת: הספק מתחבר כמודול נפרד, והלוגיקה של ההזמנה, הסל והסטטוסים נשארת ללא שינוי. ההחלפה מסתכמת ברישום מודול חדש, העברת מפתחות גישה ומיפוי סטטוסי התשלום למצבי ההזמנה הפנימיים.
אנו מחזיקים את המתאמים כך שהלוגיקה העסקית לא יודעת על שער תשלומים מסוים — אז המעבר אורך ימים ולא שבועות, והעסקאות הישנות נשארות זמינות להתאמה ולהחזרים.
כיצד לבדוק תשלום מבלי לבצע חיובים אמיתיים?
כל ספק מספק סביבת בדיקה עם מפתחות נפרדים וארגז חול. אנו מריצים תרחיש מלא: תשלום מוצלח, סירוב בנק, פסק זמן, ניסיון חוזר, ביטול מצד הלקוח. בנפרד אנו בודקים התראות אסינכרוניות — דווקא עליהן לרוב נשברת עיבוד הסטטוסים, כאשר התשובה מגיעה באיחור או מוכפלת.
כיצד בנויים החזרים והחזרים חלקיים?
ההחזר מיוזם מהאדמין או דרך אירוע הזמנה, לאחר מכן נשלחת בקשה לספק והתוצאה נרשמת. אנו מטפלים בהחזר מלא ובהחזר חלקי, שומרים על הקשר לעסקה המקורית ולא מאפשרים להחזיר יותר ממה ששולם. אם הספק תומך בהחזרים אסינכרוניים, הסטטוס נמשך לפי התראה ולא לפי סקר — ההזמנה לא נתקעת במצב ביניים.
מה עם אבטחה וגישה לנתוני תשלום?
מפתחות גישה נשמרים במשתני סביבה ולא נכנסים למאגר, וובהוקים נבדקים לפי חתימה, ונתוני כרטיסים לא עוברים דרך הקוד שלנו — אותם מעבד הספק עצמו. זה מסיר את רוב הדרישות להגנת מידע תשלומי מצדכם.
אם המקרה שלכם לא נכנס לרשימה — תארו את המשימה, נחזור עם הערכה ותוכנית עבודה.
נדון במשימה שלכם לאינטגרציה של שערי תשלום ב-Medusa.js
כדי שההערכה לאינטגרציה של שערי תשלום ב-Medusa.js תהיה מבוססת ולא "פחות או יותר", כבר בהתחלה צריך לסגור כמה פרמטרים.
Medusa היא פלטפורמת headless: תשלומים כאן מתחברים כמודול-ספק נפרד, ולכן היקף העבודה הסופי תלוי לא רק במספר השערים, אלא גם באופן שבו בנויים אצלכם הזמנות, החזרים וסטטוסי תשלום.
מה מבררים בשיחה הראשונה:
- אילו שערים ואמצעי תשלום נדרשים (כרטיסים, ארנקים, תשלומים, תשלום לפי חשבונית) ובאילו מדינות אתם מקבלים תשלומים;
- תרחישים: תשלום חד-שלבי או דו-שלבי (אישור + חיוב), החזרים חלקיים, ביטול, ניסיונות חוזרים;
- כיצד מטופלים כעת וובהוקים ומה קורה להזמנה אם התשלום נתקע או נכשל;
- דרישות ל-3-D Secure ולאימות זהות המשלם;
- האם כבר קיימים חשבונות במערכות התשלום או שצריך לפתוח אותם;
- כיצד בנוי החשבונאות: האם צריך לסנכרן תשלומים עם הנהלת חשבונות והמחסן;
- אילו סביבות והרשאות גישה קיימות כעת ומי בצד שלכם מקבל החלטות בנוגע לתשלומים.
לפי הנתונים האלה אנחנו חוזרים עם הערכה ותוכנית: הרכב מודולי-הספקים, סכימת מעבר התשלום, היקף ההתאמות בהזמנות ובהחזרים, לוחות זמנים ליישום לפי שלבים ונקודות שבהן נדרשים אישורים מצדכם. אם במהלך הדרך מתגלים תרחישים לא ברורים — מתעדים אותם בנפרד, כדי שהם לא יצופו כבר בפרודקשן.
תארו את המשימה בצורה חופשית: אילו שערים, אילו תרחישי תשלום, מה כבר עובד. זה מספיק כדי שנחזור עם הערכה, תוכנית ולוחות זמנים ליישום.
