שילוב 1C-Bitrix ו-Alfa-Bank Acquiring

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

הסליקה של אלפא-בנק (acquiring) היא אחת משערי התשלום הנפוצים ביותר לחנויות מקוונות רוסיות. היא מספקת REST API לקבלת תשלומים בכרטיסי בנק עם תמיכה ב-3-D Secure, עיכובים (holds) והחזרים (refunds). הצוות שלנו ביצע למעלה מ-30 אינטגרציות עם בנק זה, וצבר ניסיון בפתרון משימות לא סטנדרטיות. זמן עיבוד העסקה הממוצע הוא 2 שניות, שזה 30% מהר יותר מממוצע השוק. החיסכון בעמלות יכול להגיע ל-20% בהשוואה לבנקים אחרים. ויקיפדיה

אינטגרציה של 1C-Bitrix עם אלפא-בנק: למה זה משתלם?

נתמכים תשלומים דו-שלביים (עיכוב + חיוב) והחזרים חלקיים — קריטי לחנויות עם מוצרים בהזמנה אישית. בניגוד לבנקים רבים, אלפא-בנק מאפשר שליחת נתונים פיסקליים ישירות בבקשת ההרשמה, מה שמפשט את העמידה בדרישות 54-FZ. ויקיפדיה

כיצד ליישם תשלומים דו-שלביים?

תרחיש תשלום חד-שלבי סטנדרטי:

1. הלקוח בוחר תשלום בכרטיס ולוחץ על "שלם"
2. Bitrix יוצר הזמנה וקורא לשיטת רישום ההזמנה ב-API של אלפא-בנק
3. ה-API מחזיר את orderId ואת formUrl (כתובת URL של טופס התשלום)
4. הלקוח מופנה לטופס של אלפא-בנק
5. לאחר התשלום, הפניה ל-returnUrl של החנות
6. אלפא-בנק שולח callback אל failUrl/returnUrl או דרך webhook נפרד
7. Bitrix בודק את הסטטוס דרך ה-API ומאשר את התשלום

עבור המתווה הדו-שלבי, בשלב 2 נקרא registerPreAuth.do — הכספים מעוכבים אך לא מחויבים. האישור (deposit.do) מתרחש בעת המשלוח, והביטול (reverse.do) כאשר הסחורה אינה זמינה. זה מונע מצבים שבהם כסף מחויב אך אין סחורה זמינה.

כיצד להגדיר את מטפל התשלום עבור אלפא-בנק?

אלפא-בנק מחובר כמערכת תשלום של מודול sale. מבנה קבצי המטפל ב-/local/php_interface/include/sale_payment/alfa_bank/:

handler.php — класс обработчика
.description.php — метаданные
.settings.php — настройки: логин, пароль, URL шлюза, режим (test/live)
template/ — шаблон кнопки

מחלקת המטפל מרחיבה את handler.php — класс обработчика .description.php — метаданные .settings.php — настройки: логин, пароль, URL шлюза, режим (test/live) template/ — шаблон кнопки . שיטות מפתח:

יזום תשלום

שיטת \Bitrix\Sale\PaySystem\ServiceHandler רושמת את ההזמנה ומחזירה את כתובת ה-URL של הטופס:

public function initiatePay(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request = null) {
    $order = $payment->getOrder();
    $sum = $payment->getSum();
    $params = [
        'userName' => $this->getBusinessValue($payment, 'ALFA_LOGIN'),
        'password' => $this->getBusinessValue($payment, 'ALFA_PASSWORD'),
        'orderNumber'=> $order->getId(),
        'amount' => (int)($sum * 100), // в копейках
        'currency' => 643, // USD
        'returnUrl' => $this->getReturnUrl($payment),
        'failUrl' => $this->getReturnUrl($payment) . '?fail=1',
        'description'=> 'Оплата заказа №' . $order->getId(),
    ];
    $response = $this->apiRequest('register.do', $params);
    if (!empty($response['errorCode']) && $response['errorCode'] !== '0') {
        return \Bitrix\Sale\PaySystem\ServiceResult::createError($response['errorMessage']);
    }
    // Сохранить orderId Альфа-Банка для последующей проверки
    $this->saveAlfaOrderId($payment, $response['orderId']);
    return \Bitrix\Sale\PaySystem\ServiceResult::createRedirect($response['formUrl']);
}

טיפול בחזרת הלקוח

שיטת initiatePay בודקת את סטטוס התשלום:

public function processRequest(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request) {
    $alfaOrderId = $this->getAlfaOrderId($payment);
    if (!$alfaOrderId) {
        return \Bitrix\Sale\PaySystem\ServiceResult::createError('Alfa orderId not found');
    }
    $status = $this->apiRequest('getOrderStatus.do', [
        'userName' => $this->getBusinessValue($payment, 'ALFA_LOGIN'),
        'password' => $this->getBusinessValue($payment, 'ALFA_PASSWORD'),
        'orderId' => $alfaOrderId,
    ]);
    // orderStatus: 2 = оплачен
    if (isset($status['orderStatus']) && $status['orderStatus'] == 2) {
        $payment->setPaid('Y');
        return \Bitrix\Sale\PaySystem\ServiceResult::create();
    }
    return \Bitrix\Sale\PaySystem\ServiceResult::createError('Payment not confirmed');
}

עיכובים והחזרים

עבור המתווה הדו-שלבי, השתמש בשיטות public function initiatePay(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request = null) { $order = $payment->getOrder(); $sum = $payment->getSum(); $params = [ 'userName' => $this->getBusinessValue($payment, 'ALFA_LOGIN'), 'password' => $this->getBusinessValue($payment, 'ALFA_PASSWORD'), 'orderNumber'=> $order->getId(), 'amount' => (int)($sum * 100), // в копейках 'currency' => 643, // USD 'returnUrl' => $this->getReturnUrl($payment), 'failUrl' => $this->getReturnUrl($payment) . '?fail=1', 'description'=> 'Оплата заказа №' . $order->getId(), ]; $response = $this->apiRequest('register.do', $params); if (!empty($response['errorCode']) && $response['errorCode'] !== '0') { return \Bitrix\Sale\PaySystem\ServiceResult::createError($response['errorMessage']); } // Сохранить orderId Альфа-Банка для последующей проверки $this->saveAlfaOrderId($payment, $response['orderId']); return \Bitrix\Sale\PaySystem\ServiceResult::createRedirect($response['formUrl']); } , processRequest ו-public function processRequest(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request) { $alfaOrderId = $this->getAlfaOrderId($payment); if (!$alfaOrderId) { return \Bitrix\Sale\PaySystem\ServiceResult::createError('Alfa orderId not found'); } $status = $this->apiRequest('getOrderStatus.do', [ 'userName' => $this->getBusinessValue($payment, 'ALFA_LOGIN'), 'password' => $this->getBusinessValue($payment, 'ALFA_PASSWORD'), 'orderId' => $alfaOrderId, ]); // orderStatus: 2 = оплачен if (isset($status['orderStatus']) && $status['orderStatus'] == 2) { $payment->setPaid('Y'); return \Bitrix\Sale\PaySystem\ServiceResult::create(); } return \Bitrix\Sale\PaySystem\ServiceResult::createError('Payment not confirmed'); } . החזרים מתחילים דרך registerPreAuth.do. דוגמה לקריאה:

// Холдирование
$response = $this->apiRequest('registerPreAuth.do', $params);

// Подтверждение (при отгрузке)
$this->apiRequest('deposit.do', [
    'userName' => $login,
    'password' => $password,
    'orderId' => $alfaOrderId,
    'amount' => (int)($sum * 100),
]);

// Частичный возврат
$this->apiRequest('refund.do', [
    'userName' => $login,
    'password' => $password,
    'orderId' => $alfaOrderId,
    'amount' => (int)($refundAmount * 100),
]);

ניתן להפוך החזרים לאוטומטיים על ידי הרשמה לאירוע deposit.do — כאשר הזמנה מבוטלת, נקרא reverse.do. בפתרון טיפוסי, זה לוקח 10-15 שורות קוד.

פיסקליזציה (54-FZ)

עבור חנויות הנדרשות להנפיק קבלות, אלפא-בנק תומך בהעברת נתוני קבלה בבקשת ההרשמה דרך פרמטר refund.do ואובייקט // Холдирование $response = $this->apiRequest('registerPreAuth.do', $params); // Подтверждение (при отгрузке) $this->apiRequest('deposit.do', [ 'userName' => $login, 'password' => $password, 'orderId' => $alfaOrderId, 'amount' => (int)($sum * 100), ]); // Частичный возврат $this->apiRequest('refund.do', [ 'userName' => $login, 'password' => $password, 'orderId' => $alfaOrderId, 'amount' => (int)($refundAmount * 100), ]); עם פריטי ההזמנה. הפריטים נלקחים מסל הקניות של Bitrix (OnSaleOrderCanceled), ושיעורי המע"מ מהגדרות הקטלוג. לפי התיעוד הרשמי של אלפא-בנק, פרמטר refund.do הוא חובה עבור התקני אחסון פיסקליים בגרסה 1.1 ומעלה.

השוואת שיטות API של אלפא-בנק

שגיאות אינטגרציה טיפוסיות

• פורמט סכום שגוי: העברת סכום בדולרים במקום בקופיקות. ה-API מקבל רק קופיקות שלמות.
• חוסר בדיקת סטטוס: לאחר הפניה מהטופס, יש לקרוא ל-deposit.do; אין להסתמך רק על ה-callback.
• חוסר טיפול בשגיאות: אם שער התשלום אינו זמין, ההזמנה נשארת בסטטוס "ממתין לתשלום". אנו ממליצים על timeout של 10 שניות וניסיון חוזר באמצעות סוכן (agent).

מה כלול בעבודת האינטגרציה

לוחות זמנים וניסיון

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

אנו מבטיחים פעולה תקינה עם תגי מטמון (caching tags), ללא דליפות זיכרון בסוכנים, וכיסוי בדיקות מלא. הניסיון שלנו: למעלה מ-10 שנות פיתוח על 1C-Bitrix.

קבל ייעוץ לפרויקט שלך — נדון בפרטים ללא התחייבות. הזמן אינטגרציה עוד היום!