ה-API של PayPlus: יצירת קישורי תשלום מהמערכת שלך

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

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

הבסיס

יצירת קישור תשלום:

POST https://restapi.payplus.co.il/api/v1.0/PaymentPages/generateLink

האימות הוא צמד כותרות: api-key ו-secret-key. שניהם מונפקים בממשק של PayPlus.

בבקשה נדרש גם payment_page_uid - וזו נקודת המעידה הראשונה. הוא מזהה לאיזה דף תשלום מוגדר מייצרים קישור, והוא לא נוצר על ידי ה-API: מגדירים דף תשלום בממשק ומקבלים ממנו את המזהה. אם אין לך אותו, אף קריאה לא תעבוד, ואין קיצור דרך בקוד.

התיעוד יושב ב-docs.payplus.co.il, וכל פונקציה מציגה בו את כתובות ה-Staging וה-Production שלה.

מה שהופך אותו לנוח: סביבת Staging

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

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

מעשית: להחזיק את כתובת הבסיס, את ה-api-key, את ה-secret-key ואת ה-payment_page_uid כארבעה משתני סביבה נפרדים. בדיקות אוטומטיות מצביעות תמיד על Staging. המעבר לייצור הוא שינוי תצורה, לא שינוי קוד.

קישור הוא לא session - ומה שנגזר מזה

ההבדל המהותי מול iframe: קישור תשלום הוא כתובת שאפשר לשלוח, להעביר הלאה, ולפתוח מחר.

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

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

מקור האמת: הודעת שרת, לא הדפדפן

כמו בכל סולק, זו הנקודה שקובעת כמה הזמנות "נעלמות".

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

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

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

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

מי מפיק את החשבונית

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

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

אבטחה

• שני המפתחות הם סודות שרת. secret-key מאפשר לחייב לקוחות בשם העסק. לא בקוד המקור, לא בלוגים, ולא בשום דבר שרץ בדפדפן.
• לא לגעת בפרטי כרטיס. הם מוזנים בדף של PayPlus. אל תעביר אותם, אל תתעד אותם - אחרת אתה נכנס להיקף PCI DSS.
• לאמת את ההודעה הנכנסת. נקודת קצה ציבורית שמסמנת הזמנות כמשולמות היא יעד מובן מאליו.
• להצליב סכום תמיד. גם כשהכול נראה תקין. זו ההגנה שתופסת מה שהשאר פספסו.

צ'קליסט לפני העלייה לאוויר

1. לוודא שיש payment_page_uid מוגדר, ושכל ארבעת הערכים הם משתני סביבה.
2. לבנות את כל הזרימה מול Staging, כולל כישלון.
3. לבדוק את התרחיש שבו הלקוח משלם וסוגר מיד - האם ההזמנה עודכנה?
4. לבדוק תשלום כפול על אותו קישור.
5. להחליט על תוקף הקישור ולוודא שהוא נאכף.
6. לוודא שאין הפקת מסמך כפולה.

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