Kaspi Pay Integration with 1C-Bitrix: from API to QR Payment

We often get requests from online stores in Kazakhstan: how to connect Kaspi Pay to a 1C-Bitrix website? Standard payment modules don't account for the specifics of the Kaspi eCommerce API Official Kaspi eCommerce API documentation - you have to write your own integration. Without a ready-made solution - manual order processing, errors with incorrect phone numbers, lack of callback verification (fraud risk). Our approach is to build a turnkey solution in 3-5 days, with training and documentation.

Kaspi Pay is a payment tool within the Kaspi Bank ecosystem, widely used in Kazakhstan. The buyer scans a QR code or enters a phone number, then confirms payment in the Kaspi app. For online stores, this is one of the highest-converting payment methods - Kaspi Pay gives conversion rates 2-3 times higher than classic card payments, with a commission of only 1.5–2.5%. As a result, stores save up to 30% on fees compared to regular acquiring.

How the Kaspi eCommerce API Works

Kaspi provides several methods for online stores:

• QR payment - a QR code with an invoice is generated. The buyer scans it with the Kaspi.kz app. Used both online and offline.
• Kaspi Pay by link - a link leads to a confirmation form in the browser or opens the Kaspi app.
• Kaspi eCommerce API - for online stores, direct API integration.

For Bitrix integration, the standard approach is eCommerce API or payment link. Authorization via Bearer token. Base URL: https://api.kaspi.kz/payment/

$token = $this->getBusinessValue($payment, 'KASPI_TOKEN');
$orderId = $payment->getOrder()->getId();
$amount = $payment->getSum(); // in tenge (KZT)

// Create payment
$payload = [
    'device' => [
        'platformType' => 'WEB',
        'id' => md5($orderId),
    ],
    'amount' => [
        'value' => $amount,
        'currency' => 'KZT',
    ],
    'externalId' => (string)$orderId,
    'description' => 'Payment for order #' . $orderId,
    'paymentType' => 'ECOM',
    'customer' => [
        'phone' => $phone, // customer phone in format +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'] - redirect URL
// $response['data']['paymentId'] - payment ID for status checks

Why Callback Verification Is Critical

Without verification, an attacker could send a fake callback with status COMPLETED. Kaspi sends a POST to the callbackUrl when the payment status changes. Always make an additional GET request to the API to confirm the status.

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

// Verification via signature header or separate status request
if ($status === 'COMPLETED') {
    // Confirm via a separate GET request to protect against fake notifications
    $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']);

Important: always verify the status via an additional GET request to the API. Accepting the status only from the callback body is a fraud risk.

QR Code on the Order Page

An alternative UX for mobile users - a QR code directly on the checkout page:

// Get QR code for payment
$qrResponse = $this->httpPost('https://api.kaspi.kz/payment/api/v1/payments/qr', $payload, $headers);
$qrBase64 = $qrResponse['data']['qrCode']; // base64 PNG image
echo '<img src="data:image/png;base64,' . $qrBase64 . '" alt="Kaspi Pay QR">';
echo '<p>Scan the QR code in the Kaspi app</p>';

Additionally, implement polling or WebSocket for auto-updating the status on the page without reload.

Typical Integration Mistakes

• Incorrect phone format - passing the number without country code or with extra characters. Kaspi requires the format +77XXXXXXXXX. Check before sending.
• Lack of callback verification - many developers accept the status from the POST body without additional checks. This allows attackers to forge a successful payment.
• Ignoring polling for QR - if you don't implement periodic status checks, the user will remain on the QR page after payment, not seeing the order change.

Kazakhstan Market Specifics

• Currency - tenge (KZT). Amounts without kopecks (integers).
• Phones in format +77XXXXXXXXX (check with Kaspi).
• Kaspi Pay is popular for payments from 5,000 to 500,000 KZT - the main audience.
• Kaspi Red - installment, requires separate merchant setup. We include it on request.

What's Included in the Work

Work Process

1. Analytics - merchant registration, webhook setup, test keys.
2. Design - choosing methods (QR, API, link), callback verification scheme.
3. Implementation - creating a payment module for Bitrix, considering infoblocks and ORM.
4. Testing - on Kaspi test environment, checking callbacks, refunds.
5. Deployment and training - moving to production, setting access rights, documentation.

Timeline and Experience

Estimated timeline - 3 to 5 business days depending on complexity. We have 5+ years of experience with Kaspi Pay integrations, 50+ projects on 1C-Bitrix. We'll assess your project in 1 day - just contact us.

Get a consultation on integration - we'll help you choose the optimal method and avoid typical mistakes (incorrect phone format, lack of verification). Order a turnkey Kaspi Pay integration.