Інтеграція 1С-Бітрікс із платіжною системою Kaspi Pay (Казахстан)

Інтеграція 1С-Bitrix з платіжною системою Kaspi Pay (Казахстан)

Kaspi Pay — платіжний інструмент екосистеми Kaspi Bank. Широко розповсюджений у Казахстані: покупець сканує QR-код або вводить номер телефону, підтверджує оплату в додатку Kaspi. Для інтернет-магазинів актуальний як один з найбільш конверсійних методів оплати на казахстанському ринку.

Варіанти інтеграції

Kaspi надає кілька методів для інтернет-магазинів:

QR-оплата — генерується QR-код зі рахунком. Покупець сканує через додаток Kaspi.kz. Використовується як на сайті, так і в офлайн-точках.

Kaspi Pay за посиланням — посилання ведить на форму підтвердження у браузері або відкриває додаток Kaspi.

Kaspi eCommerce API — для інтернет-магазинів, пряма інтеграція через API.

Для інтеграції з Bitrix стандартний підхід — eCommerce API або платіжне посилання.

Kaspi eCommerce API

Авторизація через Bearer токен. Базовий URL: 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 платежу для перевірки статусу

Обробка сповіщень

Kaspi відправляє POST на callbackUrl при зміні статусу платежу:

$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-код на сторінці замовлення

Альтернативний UX для мобільних користувачів — 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 для автообновлення статусу на сторінці без перезавантаження.

Особливості казахстанського ринку

• Валюта — тенге (KZT). Суми без копійок (цілі числа)
• Телефони у форматі +77XXXXXXXXX (7 або 8 на початку — уточніть формат у Kaspi)
• Kaspi Pay популярний для оплат від 5 000 до 500 000 KZT — основна аудиторія
• Kaspi також надає розстрочку (Kaspi Red) — окремена інтеграція

Терміни розробки