שילוב Kaspi Pay עם 1C-Bitrix: מ-API לתשלום ב-QR

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

Kaspi Pay הוא כלי תשלום במערכת האקולוגית של Kaspi Bank, הנפוץ בקזחסטן. הקונה סורק קוד QR או מזין מספר טלפון, ואז מאשר את התשלום באפליקציית Kaspi. עבור חנויות מקוונות, זו אחת משיטות התשלום עם ההמרה הגבוהה ביותר - Kaspi Pay נותן שיעורי המרה גבוהים פי 2-3 מתשלומים בכרטיס רגיל, עם עמלה של 1.5–2.5% בלבד. כתוצאה מכך, חנויות חוסכות עד 30% בעמלות בהשוואה לסליקה רגילה.

כיצד פועל Kaspi eCommerce API

Kaspi מספק מספר שיטות לחנויות מקוונות:

• תשלום QR - נוצר קוד QR עם חשבונית. הקונה סורק אותו עם אפליקציית Kaspi.kz. משמש גם באינטרנט וגם במצב לא מקוון.
• Kaspi Pay באמצעות קישור - קישור מוביל לטופס אישור בדפדפן או פותח את אפליקציית Kaspi.
• Kaspi eCommerce API - לחנויות מקוונות, אינטגרציה ישירה דרך API.

לאינטגרציה עם Bitrix, הגישה הסטנדרטית היא eCommerce API או קישור תשלום. אימות באמצעות Bearer token. כתובת בסיס: https://api.kaspi.kz/payment/

$token = $this->getBusinessValue($payment, 'KASPI_TOKEN');
$orderId = $payment->getOrder()->getId();
$amount = $payment->getSum(); // в тенге (KZT)

// Создание платежа
$payload = [
    'device' => [
        'platformType' => 'WEB',
        'id' => md5($orderId),
    ],
    'amount' => [
        'value' => $amount,
        'currency' => 'KZT',
    ],
    'externalId' => (string)$orderId,
    'description' => 'Оплата заказа №' . $orderId,
    'paymentType' => 'ECOM',
    'customer' => [
        'phone' => $phone, // телефон покупателя в формате +77XXXXXXXXX
    ],
    'redirectUrl' => $returnUrl,
    'callbackUrl' => $callbackUrl,
];

$ch = curl_init('https://api.kaspi.kz/payment/api/v1/payments/create');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer ' . $token,
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// $response['data']['paymentLink'] — ссылка для редиректа
// $response['data']['paymentId'] — ID платежа для проверки статуса

מדוע אימות Callback הוא קריטי

ללא אימות, תוקף יכול לשלוח callback מזויף עם סטטוס COMPLETED. Kaspi שולח POST אל $token = $this->getBusinessValue($payment, 'KASPI_TOKEN'); $orderId = $payment->getOrder()->getId(); $amount = $payment->getSum(); // в тенге (KZT) // Создание платежа $payload = [ 'device' => [ 'platformType' => 'WEB', 'id' => md5($orderId), ], 'amount' => [ 'value' => $amount, 'currency' => 'KZT', ], 'externalId' => (string)$orderId, 'description' => 'Оплата заказа №' . $orderId, 'paymentType' => 'ECOM', 'customer' => [ 'phone' => $phone, // телефон покупателя в формате +77XXXXXXXXX ], 'redirectUrl' => $returnUrl, 'callbackUrl' => $callbackUrl, ]; $ch = curl_init('https://api.kaspi.kz/payment/api/v1/payments/create'); curl_setopt($ch, CURLOPT_HTTPHEADER, [ 'Content-Type: application/json', 'Authorization: Bearer ' . $token, ]); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = json_decode(curl_exec($ch), true); curl_close($ch); // $response['data']['paymentLink'] — ссылка для редиректа // $response['data']['paymentId'] — ID платежа для проверки статуса כאשר סטטוס התשלום משתנה. בצע תמיד בקשת GET נוספת ל-API כדי לאשר את הסטטוס.

$rawBody = file_get_contents('php://input');
$data = json_decode($rawBody, true);
$paymentId = $data['data']['paymentId'];
$externalId = $data['data']['externalId']; // наш orderId
$status = $data['data']['status']; // 'COMPLETED', 'FAILED', 'EXPIRED'

// Верификация через заголовок подписи или дополнительный запрос статуса
if ($status === 'COMPLETED') {
    // Подтвердить через отдельный GET-запрос для защиты от фальшивых уведомлений
    $verification = $this->httpGet(
        'https://api.kaspi.kz/payment/api/v1/payments/' . $paymentId,
        [],
        ['Authorization: Bearer ' . $token]
    );
    if ($verification['data']['status'] === 'COMPLETED') {
        $order = \Bitrix\Sale\Order::loadByAccountNumber($externalId);
        // setPaid('Y'), save()
    }
}

http_response_code(200);
echo json_encode(['status' => 'OK']);

חשוב: אמת תמיד את הסטטוס באמצעות בקשת GET נוספת ל-API. קבלת הסטטוס רק מגוף ה-callback היא סיכון להונאה.

קוד QR בעמוד ההזמנה

חוויית משתמש חלופית למשתמשי מובייל - קוד QR ישירות בעמוד התשלום:

// Получить QR-код для оплаты
$qrResponse = $this->httpPost('https://api.kaspi.kz/payment/api/v1/payments/qr', $payload, $headers);
$qrBase64 = $qrResponse['data']['qrCode']; // base64 PNG изображение
echo '<img src="data:image/png;base64,' . $qrBase64 . '" alt="Kaspi Pay QR">';
echo '<p>Отсканируйте QR в приложении Kaspi</p>';

בנוסף, הטמע polling או WebSocket לעדכון אוטומטי של הסטטוס בעמוד ללא רענון.

טעויות אינטגרציה נפוצות

• פורמט טלפון שגוי - העברת המספר ללא קידומת מדינה או עם תווים נוספים. Kaspi דורש את הפורמט +77XXXXXXXXX. בדוק לפני השליחה.
• חוסר אימות callback - מפתחים רבים מקבלים את הסטטוס מגוף ה-POST ללא בדיקות נוספות. זה מאפשר לתוקפים לזייף תשלום מוצלח.
• התעלמות מ-polling עבור QR - אם לא תטמיע בדיקות סטטוס תקופתיות, המשתמש יישאר בעמוד ה-QR לאחר התשלום, ולא יראה את שינוי ההזמנה.

מאפייני שוק קזחסטן

• מטבע - טנגה (KZT). סכומים ללא אגורות (מספרים שלמים).
• טלפונים בפורמט +77XXXXXXXXX (בדוק עם Kaspi).
• Kaspi Pay פופולרי לתשלומים מ-5,000 עד 500,000 KZT - הקהל המרכזי.
• Kaspi Red - תשלומים בתשלומים, דורש הגדרת סוחר נפרדת. אנו כוללים זאת לפי בקשה.

מה כלול בעבודה

תהליך העבודה

1. אנליטיקה - רישום סוחר, הגדרת webhook, מפתחות בדיקה.
2. עיצוב - בחירת שיטות (QR, API, קישור), סכמת אימות callback.
3. יישום - יצירת מודול תשלום עבור Bitrix, תוך התחשבות ב-infoblocks ו-ORM.
4. בדיקות - בסביבת הבדיקה של Kaspi, בדיקת callbacks, החזרים.
5. פריסה והדרכה - מעבר לסביבת ייצור, הגדרת הרשאות גישה, תיעוד.

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

לוח זמנים משוער - 3 עד 5 ימי עסקים בהתאם למורכבות. יש לנו ניסיון של 5+ שנים באינטגרציות Kaspi Pay, 50+ פרויקטים על 1C-Bitrix. נבחן את הפרויקט שלך תוך יום אחד - פשוט צור קשר.

קבל ייעוץ על אינטגרציה - נעזור לך לבחור את השיטה האופטימלית ולהימנע מטעויות נפוצות (פורמט טלפון שגוי, חוסר אימות). הזמן אינטגרציית Kaspi Pay סוהר.