ה-API של קארדקום v11: גביית תשלומים מהמערכת שלך

קארדקום היא אחד הסולקים הוותיקים בישראל, וממשק ה-LowProfile שלה הוא הדרך הנפוצה לקבל תשלום מאתר או ממערכת: אתה יוצר דף תשלום, מפנה אליו את הלקוח (או מטמיע אותו ב-iframe), והסליקה עצמה מתרחשת אצל קארדקום - כך שפרטי כרטיס האשראי לא עוברים דרך השרת שלך כלל.

המדריך הזה מתייחס ל-v11, וההבדלים בינה לבין הממשקים הישנים הם בדיוק המקום שבו נופלים.

יצירת דף תשלום

הקריאה היא:

POST https://secure.cardcom.solutions/api/v11/LowProfile/Create

השדות המרכזיים בגוף הבקשה:

• TerminalNumber - מספר המסוף. חייב להישלח כמספר שלם ולא כמחרוזת.
• ApiName - שם המשתמש ב-API
• Operation - מה לעשות: חיוב בלבד, יצירת טוקן, או שילוב
• Amount ו-ISOCoinId - סכום ומטבע
• ReturnValue - השדה החשוב ביותר בפרקטיקה. זה שדה חופשי שחוזר אליך כמות שהוא. שים בו את מזהה ההזמנה שלך.
• SuccessRedirectUrl ו-FailedRedirectUrl - לאן הדפדפן מופנה
• WebHookUrl - לאן קארדקום מודיעה לשרת שלך
• Language
• Document - אובייקט אופציונלי להפקת מסמך אוטומטית

בתשובה מתקבלים LowProfileId - לשמור אותו על ההזמנה - ו-Url, שאליו מפנים או שאותו מטמיעים ב-iframe. אם ביט או PayPal מופעלים במסוף, יחזרו גם UrlToBit ו-UrlToPayPal.

שלוש מלכודות של v11 שגורמות לרוב התקלות

1. ResponseCode, לא DealResponse

זו הטעות היקרה ביותר. ב-v11 בודקים הצלחה לפי ResponseCode == 0. השדה DealResponse, שמופיע בהמון דוגמאות ברשת ובספריות ישנות, לא קיים ב-v11 בכלל.

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

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

2. סוגי מסמכים הם מחרוזות, לא מספרים

אם אתה מבקש מקארדקום להפיק מסמך אוטומטית, השדה DocumentTypeToCreate ב-v11 הוא אֵנוּם מחרוזתי: "TaxInvoiceAndReceipt", "TaxInvoice", "Receipt" וכדומה.

הקודים המספריים שאתה עשוי למצוא בדוגמאות - 101, 400 וחבריהם - שייכים לממשקי ה-.aspx הישנים ולא ל-v11. שליחת מספר במקום מחרוזת תיכשל.

3. ApiPassword לא נשלח בקריאה רגילה

ApiPassword אינו נשלח בקריאת LowProfile/Create רגילה ולא בחיוב עסקה רגיל. אם הוספת אותו כי ראית אותו איפשהו, כדאי לבדוק מול התיעוד באיזו פעולה הוא באמת נדרש - שליחת שדות מיותרים היא דרך קלה לקבל שגיאת ולידציה מבלבלת.

ההחלטה הארכיטקטונית: webhook או הפניה

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

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

הכלל: ה-webhook מעדכן את מצב ההזמנה. ההפניה מציגה למשתמש מסך תודה. אף פעם לא להפך.

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

ההחלטה השנייה: מי מפיק את המסמך

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

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

אבטחה ותאימות

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

לפני העלייה לאוויר

1. לאמת שהמסוף שלך אכן על v11 ושמופעל בו LowProfile.
2. לבדוק את מסלול ה-webhook מקצה לקצה, לא רק את ההפניה.
3. לבדוק במפורש את התרחיש שבו הלקוח סוגר את הלשונית מיד אחרי התשלום.
4. להחליט אם Document נדרש אצלך, ולוודא שאין הפקה כפולה.
5. לבדוק כישלון אמיתי, לא רק הצלחה - FailedRedirectUrl ו-ResponseCode שאינו אפס.

להשוואה בין הסולקים הישראליים, ראה השוואת סולקים ישראליים למפתחים.