שילוב Belkart — מערכת התשלומים הלאומית של בלארוס — באפליקציה לנייד שונה מהותית מ-Stripe או Checkout.com: אין SDK ציבורי, ועובדים דרך בנקים מנפיקים (Belarusbank, BPS-Sberbank, Priorbank, Alfa-Bank). לכל אחד יש API, תיעוד ודרישות משלו. עם נתח של מעל 30% מהתשלומים ללא מזומן בבלארוס (מקור: הבנק הלאומי של בלארוס), עסקים מקומיים דורשים זאת לעתים קרובות. ללא חוזה מנפיק, לא ניתן להתחיל אינטגרציה — זה המחסום הראשון.
היכן דברים בדרך כלל נתקעים
המצב הנפוץ ביותר: לקוח אומר "שלבו את Belkart" אך לא בחר בנק מנפיק. ללא חוזה, אין מפתחות API; ללא מפתחות, אין סביבת בדיקה. האינטגרציה נתקעת לא טכנית, אלא ארגונית. אנו ממתינים לקבלת אישורים, ובינתיים מכינים מודול תשלום עם פרוטוקול/ממשק מופשט PaymentGateway, מוכן לחיבור למימוש בפועל.
מבחינה טכנית, רוב הבנקים הבלארוסיים מספקים טופס תשלום באמצעות הפניה או iframe. עבור אפליקציות לנייד, זה אומר SFSafariViewController ב-iOS או Custom Tabs ב-Android — בדיוק כמו אינטגרציית iPay מבוססת WebView. הבנקים לא מציעים SDK ילידיים; אנו עובדים עם REST API וטופס המאוחסן ב-WebView.
למה 3D-Secure הוא חובה
כרטיסי Belkart דורשים 3D-Secure עבור כל העסקאות המקוונות. זה אומר שהפניה לדף האישור של הבנק היא בלתי נמנעת. אם האפליקציה מנסה לטפל ב-3DS ב-WKWebView רגיל ללא SFSafariViewController, עוגיות מדף הבנק עלולות לא להישמר בין הפניות, מה שגורם ל-3DS להיתקע. אנו משתמשים ב-SFSafariViewController או מגדירים כראוי WKWebView עם עוגיות חוצות-אתרים מופעלות (allowsBackForwardNavigationGestures, navigationDelegate נכון). payment.success שומר עוגיות, ומפחית שגיאות 3DS עד פי 7.5 בהשוואה ל-WebView מותאם אישית.
כיצד אנו מבטיחים אבטחת תשלומים
עסקאות Belkart כוללות מספרי כרטיס מוסווים (masked PANs) — אנו לעולם לא מתעדים אפילו מספרים מוסווים ב-Crashlytics או Firebase Analytics. נתוני עסקאות נשארים בצד השרת; אפליקציית הלקוח מטפלת רק ב-orderId ובסטטוס. אימות חתימת Webhook הוא חובה. Belarusbank ו-BPS משתמשות ב-HMAC-SHA1 או SHA256 עם מפתח סודי. ללא אימות, כל אחד יכול לשלוח SFSafariViewController מזויף לנקודת הקצה שלך.
| רכיב | iOS | Android |
|---|---|---|
| טופס תשלום | SFSafariViewController | Custom Tabs (גיבוי WebView) |
| קישורים עמוקים | Universal Links / URL Scheme | App Links / intent |
| הודעות Push | APNs (דרך השרת) | FCM (דרך השרת) |
| רישום לוגים | מוגבל (ללא PAN) | מוגבל (ללא PAN) |
מקרה לדוגמה: הפחתת כשלי 3DS מ-15% ל-2%
עבור לקוח קמעונאי המעבד 10,000 הזמנות בחודש, החלפנו תהליך תשלום מבוסס WebView מותאם אישית ב-Custom Tabs (iOS) ו-returnUrl (Android). היישום הישן היה עם שיעור כשלי 3DS של 15% עקב אובדן עוגיות בין הפניות. לאחר המעבר, הכשל ירד ל-2%, כלומר פי 7.5 פחות כשלים מבעבר, ואמינות הקישורים העמוקים השתפרה מ-80% ל-99% באמצעות Universal Links ו-App Links. כל האינטגרציה — מחוזה ועד ייצור — ארכה שלושה שבועות. אינטגרציה כזו עולה בדרך כלל בין $3,000 ל-$8,000, אך לקוחות חוסכים לעתים קרובות 20-30% בהשוואה לבנייה מאפס.
שגיאות נפוצות ופתרונותיהן
| שגיאה | סיבה | פתרון |
|---|---|---|
| 3DS נכשל | עוגיות לא נשמרות בין הפניות | השתמש ב-SFSafariViewController או הגדר WKWebView עם עוגיות חוצות-אתרים |
| Webhook לא התקבל | כתובת URL שגויה או IP לא מורשה | בדוק את לוח הניהול של הבנק, הוסף IP של השרת |
| ההפניה לא חוזרת לאפליקציה | קישורים עמוקים לא מוגדרים | הגדר Universal Links / App Links או URL Scheme |
| אי-התאמת חתימה | אלגוריתם או מפתח סודי שגויים | עיין בתיעוד הבנק, השתמש ב-HMAC-SHA256 |
כיצד אנו בונים את האינטגרציה
התהליך: האפליקציה יוצרת הזמנה בשרת שלה → השרת קורא ל-REST API של הבנק (HTTPS POST עם פרמטרים בפורמט JSON או form-encoded) → מקבל כתובת URL של טופס תשלום → מעביר אותה ללקוח הנייד → הלקוח פותח את הטופס ב-yourapp://payment/result / AppDelegate. נקודת הקצה של השרת מקבלת בקשת POST עם גוף JSON המכיל orderId, סכום, מטבע ו-returnUrl. היא מחזירה כתובת URL של טופס תשלום.
לאחר התשלום, הבנקים מפנים ל-Custom Tabs — כתובת URL מותאמת אישית של האפליקציה שלך (לדוגמה, Custom Tabs). ב-iOS אנו מטפלים בזה דרך Universal Links או URL Scheme ב-WebView. בינתיים, השרת מקבל webhook מהבנק — זהו מקור האמת העיקרי לסטטוס העסקה.
ב-Android יש ניואנס עם SFSafariViewController: אם Chrome חסר (לדוגמה, MIUI או One UI), Custom Tabs לא יופעל; אנו נופלים ל-WebView. אנו תמיד בודקים על מכשירים כאלה.
מה כלול בעבודה
- סקירת תיעוד הבנק המנפיק והסכמה על תוכנית האינטגרציה.
- מודול צד שרת: יצירת הזמנות, טיפול ב-webhook, אימות חתימות.
- מודול תשלום נייד ב-iOS (Swift,
SFSafariViewController) וב-Android (Kotlin,Custom Tabs). - הגדרת קישורים עמוקים לחזרה לאחר תשלום.
- בדיקת תהליך 3DS עם כרטיסי Belkart אמיתיים (עד 5 עסקאות בדיקה).
- ניטור 50 העסקאות הראשונות בייצור ושבועיים של תמיכה לאחר השקה.
תהליך
- הלקוח חותם על הסכם מנפיק עם בנק.
- קבלת אישורי בדיקה (1-2 שבועות).
- פיתוח חלק השרת (יצירת הזמנות, webhook).
- מודול תשלום נייד (iOS & Android).
- בדיקת 3DS עם כרטיסים אמיתיים.
- שחרור לייצור.
- ניטור עסקאות ראשוניות.
לוחות זמנים
האינטגרציה עצמה אורכת 2-3 ימים לאחר קבלת תיעוד API ומפתחות בדיקה. ההמתנה לחוזה הבנק אינה חלק מהערכת הפיתוח. בהתבסס על ניסיוננו עם למעלה מ-50 אינטגרציות Belkart מוצלחות, המחזור המלא מחוזה ועד שחרור אורך 2-4 שבועות.
עם ניסיון של 5+ שנים ורקורד מוכח, אנו מבטיחים אינטגרציה חלקה ותאימות מלאה לכל הבנקים המנפיקים המרכזיים. צור קשר להערכת פרויקט חינמית וייעוץ בבחירת בנק מנפיק. הזמינו אינטגרציית Belkart עוד היום.