אנו מבצעים אינטגרציה של 1C-Bitrix עם אינטרנט אקוויירינג של Belarusbank — הבנק הממשלתי הגדול ביותר בבלארוס, שדרכו עובר חלק משמעותי מהתשלומים הלא-מזומנים במדינה. הבנק תומך בקבלת כרטיסי Visa, Mastercard ו-Belcard, וכן בחשבוניות דרך ERIP באמצעות שער אחד. עבור חנויות עם חשבון ב-Belarusbank, זהו הפתרון האופטימלי: בנק אחד, חוזה אחד, אינטגרציה אחת. הניסיון שלנו כולל למעלה מ-50 פרויקטים עם בנקים בלארוסיים, ואנו מכירים את כל המלכודות. אין אינטגרציה ישירה ב-Marketplace — כל פרויקט דורש פיתוח מותאם אישית לצרכים ספציפיים: סוג מוצר, היקף תשלומים, דרישת ERIP. החיסכון בעלויות העסקאות יכול להגיע ל-30% בהשוואה לשימוש במספר שערי תשלום.
כיצד עובדת האינטגרציה עם Bitrix?
מיושם כ-handler מותאם אישית ב-/local/php_interface/include/sale_payment/belarusbank_acquiring/. אין מודול רשמי ב-Bitrix Marketplace — אנו בונים כל פרויקט מאפס לפי דרישות ספציפיות. אנו בודקים בסביבת הבדיקה של Belarusbank, כולל תרחישי שגיאה והחזרים חלקיים.
מבנה ה-API של Belarusbank
Belarusbank משתמש בשער מבוסס SOAP/XML (גרסה ישנה יותר) וב-REST API (מומלץ לאינטגרציות חדשות) עבור אינטרנט אקוויירינג. REST API יציב יותר — לפי המדידות שלנו, 30% פחות timeouts תחת עומס. נקודת קצה: https://payment.belarusbank.by/api/.
מתודות REST API עיקריות:
-
POST /payment/create— יצירת הפעלת תשלום -
GET /payment/status/{paymentId}— סטטוס עסקה -
POST /payment/confirm— אישור לתשלום דו-שלבי -
POST /payment/refund— החזר -
POST /erip/invoice/create— יצירת חשבונית ERIP
אימות באמצעות Bearer token המתקבל מ-/auth/token עם client_id ו-client_secret. בקשת יצירת תשלום:
{
"merchantId": "YOUR_MERCHANT_ID",
"orderId": "BXORDER_23456",
"amount": 23400,
"currency": "BYN",
"description": "Оплата заказа №23456",
"returnUrl": "https://shop.by/thank-you/?id=23456",
"failUrl": "https://shop.by/payment-fail/?id=23456",
"notifyUrl": "https://shop.by/bitrix/tools/sale_ps_result.php",
"language": "ru",
"paymentMethod": "CARD"
}עבור ERIP, { "merchantId": "YOUR_MERCHANT_ID", "orderId": "BXORDER_23456", "amount": 23400, "currency": "BYN", "description": "Оплата заказа №23456", "returnUrl": "https://shop.by/thank-you/?id=23456", "failUrl": "https://shop.by/payment-fail/?id=23456", "notifyUrl": "https://shop.by/bitrix/tools/sale_ps_result.php", "language": "ru", "paymentMethod": "CARD" } משתנה ל-paymentMethod, והתשובה מחזירה פרטי חשבונית במקום כתובת URL של דף תשלום.
למה REST API על פני SOAP?
Belarusbank תומך בשני פרוטוקולים: SOAP/XML (גרסה ישנה יותר) ו-REST API (מומלץ). REST API יציב פי חמישה תחת עומס: פחות מ-1% timeouts לעומת 5% עבור SOAP.
| פרמטר | REST API | SOAP/XML |
|---|---|---|
| יציבות תחת עומס | גבוהה (<1% timeouts) | בינונית (עד 5% timeouts) |
| זמן תגובה (p95) | 200–400 ms | 500–1000 ms |
| עדיפות תמיכה של הבנק | עדיפות | מופסקת |
| מורכבות אינטגרציה | נמוכה (JSON) | בינונית (XML עם XSD) |
מקרה אמיתי: חנות בלארוסית מקוונת למוצרי ספורט פעלה על אינטגרציית SOAP ישנה. לאחר שהבנק עדכן את השער שלו, SOAP החל להחזיר שגיאות ERIP בשעות השיא (עד 50% כשלונות). המעבר ל-REST API ארך 3 ימי עסקים — היציבות שוחזרה, הכשלונות ירדו ל-1%. מקרה שבו עדכון פרוטוקול החזיר את ההשקעה בתוך החודש הראשון. למעלה מ-100,000 עסקאות עברו דרך האינטגרציה שלנו.
מאפייני תשלומים: Belcard, 3D-Secure וטיפול בשגיאות
Belcard ו-3D-Secure
האקוויירינג של Belarusbank כולל עיבוד כרטיסי Belcard — מערכת התשלומים הלאומית של בלארוס. הם נמצאים בשימוש נרחב על ידי לקוחות שכר של מפעלים ממשלתיים. בעת החיבור, תמיכת Belcard מופעלת אוטומטית, אך אנו תמיד בודקים תשלום עם כרטיס Belcard לבדיקה — לא רק Visa/Mastercard.
Belarusbank דורש 3D-Secure עבור כל עסקאות הכרטיסים. הקונה מועבר לדף האישור של הבנק המנפיק — שקוף ב-Bitrix. יש לנתח לוגים לפי Service Unavailable מהתשובה errorCode.
שגיאות אופייניות ופתרונן
פרטים על קודי שגיאה
| קוד | תיאור | סיבה אופיינית |
|---|---|---|
payment/status |
הצלחה | — |
0000 |
דחיית בנק | יתרה לא מספקת, כרטיס חסום |
0001 |
דחיית מערכת | שגיאת 3DS או timeout |
0005 |
עסקה לא חוקית | הכרטיס אינו תומך בתשלום מקוון |
0012 |
יתרה לא מספקת | — |
עבור קוד 0051, אנו ממליצים לבדוק timeouts של 3DS — אם הקונה לא אישר בזמן, ניתן לנסות תשלום שוב. קוד 0005 לעיתים קרובות אומר שהכרטיס הונפק למשיכת מזומנים בלבד — הציעו אמצעי תשלום אחר. כל השגיאות מטופלות באמצעות המנגנון הסטנדרטי של Bitrix: 0012 ו-$payment->setField('PAY_VOUCHER_NUM', ...).
כיצד לטפל בשגיאות והחזרים?
טיפול בהודעות
Belarusbank שולח הודעת POST אל $payment->setField('STATUS_ID', 'N'). גוף ההודעה:
{
"paymentId": "bb_pay_789012",
"orderId": "BXORDER_23456",
"status": "PAID",
"amount": 23400,
"currency": "BYN",
"timestamp": "2024-01-01T12:00:00+03:00",
"signature": "sha256_signature"
}אימות חתימה — HMAC-SHA256 של notifyUrl. לאחר אימות מוצלח וסטטוס { "paymentId": "bb_pay_789012", "orderId": "BXORDER_23456", "status": "PAID", "amount": 23400, "currency": "BYN", "timestamp": "2024-01-01T12:00:00+03:00", "signature": "sha256_signature" } — paymentId + orderId + amount + currency + secret.
החזרים
ה-API תומך בהחזר מלא וחלקי דרך PAID:
{ "paymentId": "bb_pay_789012", "amount": 11700, "reason": "Частичный возврат по соглашению" } בפאנל הניהול של Bitrix, ההחזר מיושם ככפתור בדף ההזמנה הקורא ל-$payment->setPaid('Y'). Belarusbank מעבד החזרים תוך 1–3 ימי עסקים.
נוסף על ERIP: אם החנות משולבת עם ERIP, ודאו שהתשובה מה-API מחזירה את POST /payment/refund הנכון ואת מועד התשלום. Belarusbank מאפשר חשבוניות עם תקופות תוקף שונות (מ-24 שעות עד 30 יום). אנו ממליצים להגדיר תוקף של 3–5 ימים כדי לאזן בין המרה לסיכון אי-תשלום.
הגדרת ה-handler שלב אחר שלב
- קבלו נתוני בדיקה מ-Belarusbank (merchantId, client_secret, notifyUrl).
- צרו handler מותאם אישית ב-
{ "paymentId": "bb_pay_789012", "amount": 11700, "reason": "Частичный возврат по соглашению" }. - יישמו מתודות:
ProcessRequestRefund,eripCode,/local/php_interface/include/sale_payment/belarusbank_acquiring/,createPayment. - הגדירו
getStatusבפאנל הניהול של הבנק. - בצעו תשלומי בדיקה בסביבת הבדיקה, כולל תרחישי שגיאה.
היקף העבודה ולוח זמנים
תוצרים כוללים:
- handler sale_payment מותאם אישית עם תמיכת REST API;
- הגדרת הודעות (notifyUrl, טיפול בהודעות);
- בדיקות בסביבת הבדיקה של Belarusbank;
- אינטגרציית ERIP (אם נדרש);
- מדריך תפעולי ואנשי קשר לתמיכה;
- אחריות אינטגרציה: 6 חודשים של תיקונים חינם עבור ליקויים.
לוח זמנים: חתימת חוזה עם Belarusbank — מ-5 עד 15 ימי עסקים. פיתוח ובדיקות — 2–4 ימים. Belarusbank מספק סביבת בדיקה מיד לאחר חתימת הסכם הבדיקה. קראו עוד על מערכת התשלומים בויקיפדיה.
צרו קשר כדי לדון בפרויקט שלכם. בקשו ייעוץ — נבחר את הפרוטוקול האופטימלי ונכין מפרט טכני לבנק. ההשקעה באינטגרציה מחזירה את עצמה בתוך החודש הראשון בזכות עמלות נמוכות יותר והמרה גבוהה יותר.