Kaspi Pay + Halyk + Forte — интеграция платежей для онлайн-магазина в Казахстане

Казахские платёжные системы — рынок 2026

Когда вы запускаете интернет-магазин в Алматы или Казахстане, первое, что нужно решить — как принимать платежи от покупателей. За 19 лет и 500+ проектов мы интегрировали казахские платёжные системы с сотнями магазинов. Выяснили что работает, а что нет.

На 2026 год рынок эквайринга в Казахстане выглядит так:

• Kaspi Pay: ~60% интернет-магазинов (самый популярный, простой старт)
• Halyk Bank: ~20% (B2B, корпоративные, надёжный)
• Forte: ~10% (премиум, 3D Secure, экспорт)
• Другие (Jusan, Altyn, БВУ): ~10% (нишевые или устаревшие)

Главное правило: не полагайтесь на одного эквайрера. Если Kaspi будет на техническом обслуживании — вы потеряете платежи. Интегрируйте минимум два параллельно. Мы рекомендуем Kaspi (основной) + Halyk (резервный).

Kaspi Pay — быстрый старт

Когда выбирать Kaspi

• Запускаетесь впервые (нужна скорость)
• Магазин <5000 товаров, оборот <100M ₸/год
• Нет требований по 3D Secure или Advanced Security
• Нужна интеграция с Kaspi Super App (мобильное приложение Kaspi)

Процесс подключения к Kaspi

1. Регистрация БИН: заявка на kaspi.kz/business → KYC документы (паспорт директора, БИН, выписка из реестра) → 3-5 дней
2. Получение API-ключа: Kaspi выдаст merchant_id и secret_key
3. Подписание договора: комиссия обычно 2.5-3.5% (зависит от оборота)
4. Тестирование: используйте sandbox учётные данные
5. Production: производство 1-2 дня

REST API Kaspi — основные endpoint'ы

// 1. Создание платежа (Initiate Payment)
POST https://api.kaspi.kz/v2/payment/create
Content-Type: application/json
Authorization: Bearer SECRET_KEY

{
  "merchantId": "YOUR_MERCHANT_ID",
  "orderId": "ORDER_123",
  "amount": 150000,
  "currency": "KZT",
  "description": "Товар: Samsung Galaxy S25",
  "returnUrl": "https://yourshop.kz/checkout/success",
  "failureUrl": "https://yourshop.kz/checkout/failure",
  "webhookUrl": "https://yourshop.kz/webhook/kaspi"
}

// Response:
{
  "transactionId": "TXN_ABC123",
  "paymentUrl": "https://kaspi.kz/checkout?token=...",
  "status": "PENDING"
}

// 2. Проверка статуса платежа (Poll Payment Status)
GET https://api.kaspi.kz/v2/payment/TXN_ABC123/status
Authorization: Bearer SECRET_KEY

// Response:
{
  "transactionId": "TXN_ABC123",
  "status": "COMPLETED",
  "amount": 150000,
  "orderId": "ORDER_123"
}

// 3. Refund (возврат денег)
POST https://api.kaspi.kz/v2/payment/TXN_ABC123/refund
Content-Type: application/json
Authorization: Bearer SECRET_KEY

{
  "amount": 150000,
  "reason": "Customer requested"
}

Webhook обработка (критично!)

Kaspi отправляет POST запрос к вашему webhook URL с результатом платежа. Никогда не полагайтесь только на redirect — webhook нужен для гарантии.

// Kaspi отправляет:
POST /webhook/kaspi
Content-Type: application/json

{
  "transactionId": "TXN_ABC123",
  "orderId": "ORDER_123",
  "status": "COMPLETED",
  "amount": 150000,
  "timestamp": "2026-05-13T14:30:00Z",
  "signature": "SHA256_HASH"
}

// Ваше приложение должно ответить:
{
  "acknowledged": true
}

// Обработка в коде (Node.js пример):
const crypto = require('crypto');

app.post('/webhook/kaspi', (req, res) => {
  const { transactionId, orderId, status, amount, signature } = req.body;

  // Проверка подписи (безопасность)
  const payload = `${transactionId}${orderId}${status}${amount}`;
  const expectedSig = crypto.createHmac('sha256', SECRET_KEY)
    .update(payload)
    .digest('hex');

  if (signature !== expectedSig) {
    return res.status(400).json({ error: 'Invalid signature' });
  }

  // Обновление заказа в БД
  if (status === 'COMPLETED') {
    await Order.findByIdAndUpdate(orderId, { status: 'paid', transactionId });
    await sendConfirmationEmail(orderId);
    await notifyWarehouse(orderId);
  } else if (status === 'FAILED') {
    await Order.findByIdAndUpdate(orderId, { status: 'payment_failed' });
  }

  res.json({ acknowledged: true });
});

Комиссии Kaspi (mai 2026)

Halyk Bank — надёжность и интеграция с 1С

Когда выбирать Halyk

• Магазин интегрирован с 1С (Halyk имеет стабильный API для синхронизации)
• Оборот 50M+ ₸ в год (Halyk даёт лучшие комиссии при высоких объёмах)
• Нужна поддержка B2B платежей (счета-фактуры)
• Приоритет надёжности над скоростью старта

Halyk API — основные отличия от Kaspi

Halyk использует похожую REST архитектуру, но с собственными endpoint'ами и форматом:

// Создание платежа у Halyk
POST https://secure.halyk.kz/api/v1/invoice
Content-Type: application/json

{
  "merchantCode": "YOUR_MERCHANT_CODE",
  "invoiceId": "INV_123",
  "amount": 150000,
  "currency": "KZT",
  "description": "Order #123",
  "notifyUrl": "https://yourshop.kz/webhook/halyk",
  "returnUrl": "https://yourshop.kz/checkout/success"
}

// Halyk возвращает:
{
  "invoiceId": "INV_123",
  "transactionId": "HALYK_TXN_456",
  "paymentUrl": "https://secure.halyk.kz/checkout?invoice=...",
  "status": "NEW"
}

Halyk комиссии (2026)

• 0 - 50M ₸: 2.9%
• 50M - 200M ₸: 2.7%
• 200M+ ₸: 2.5% (договаривается напрямую)
• Fixed fee: 30-50 ₸

Forte — премиум решение

Когда использовать Forte

• Высокий средний чек (10k+ ₸)
• Нужна 3D Secure для защиты
• Экспортируете в CIS страны (Россия, Беларусь)
• Требуется Apple Pay, Google Pay

Forte особенности

• 3D Secure: дополнительная аутентификация для платежей >100k ₸
• Recurring: встроенная система подписок (удобно для SaaS, подписных магазинов)
• Mobile Wallets: Apple Pay, Google Pay, Samsung Pay
• Комиссия: 2.7-3.2% + 50 ₸ за транзакцию

Сравнительная таблица

Паттерн интеграции нескольких эквайреров одновременно

В своих проектах мы часто интегрируем Kaspi как основной + Halyk как fallback. Вот как это устроено:

// Checkout страница (Vue.js / React пример)
const handlePayment = async (amount, orderId) => {
  // Сначала пытаемся Kaspi
  try {
    const kaspiPayment = await initPaymentKaspi({
      orderId,
      amount,
      webhookUrl: '/webhook/kaspi'
    });
    window.location = kaspiPayment.paymentUrl;
  } catch (kaspiError) {
    // Если Kaspi недоступен, падаем на Halyk
    console.warn('Kaspi failed:', kaspiError.message);
    try {
      const halykPayment = await initPaymentHalyk({
        orderId,
        amount,
        webhookUrl: '/webhook/halyk'
      });
      window.location = halykPayment.paymentUrl;
    } catch (halykError) {
      alert('Оба способа недоступны, попробуйте позже');
    }
  }
};

// Backend: улучшенная обработка webhook с retry
app.post('/webhook/payment', async (req, res) => {
  const { provider, transactionId, orderId, status } = req.body;

  try {
    // Проверка статуса (идемпотентность)
    const existingPayment = await Payment.findOne({ transactionId });
    if (existingPayment) {
      return res.json({ acknowledged: true }); // Уже обработан
    }

    if (status === 'COMPLETED') {
      // Обновляем заказ
      const order = await Order.findByIdAndUpdate(
        orderId,
        { status: 'paid', provider, transactionId },
        { new: true }
      );

      // Queue worker (важно!) - отправляем в очередь, не синхронно
      await queue.push('process_paid_order', { orderId });

      // Логируем платёж
      await Payment.create({
        orderId,
        transactionId,
        provider,
        amount: req.body.amount,
        status: 'completed'
      });
    }

    res.json({ acknowledged: true });
  } catch (error) {
    console.error('Webhook processing failed:', error);
    res.status(500).json({ error: 'Processing failed' });
  }
});

Чек-лист подключения платежей

На этапе переговоров (неделя 1)

• ☐ Выбрать 1-2 эквайрера (Kaspi + Halyk рекомендуем)
• ☐ Подать заявку на kaspi.kz/business или halyk.kz/merchant
• ☐ Подготовить документы: паспорт директора, выписка из реестра, анкета
• ☐ Договориться по комиссиям (обычно скидывают 0.3% при обороте 100M+)

На этапе разработки (неделя 2-3)

• ☐ Получить merchant_id и API-ключи от эквайрера
• ☐ Интегрировать на песочнице (sandbox) в приложение
• ☐ Тестировать все сценарии: успешный платёж, отмена, возврат
• ☐ Реализовать webhook обработку с retry logic
• ☐ Добавить логирование всех платежей в БД
• ☐ Тестировать edge-case'ы (timeout, duplicate webhook, сетевая ошибка)

На этапе production (неделя 4)

• ☐ Мониторить платежи в реальном времени (Alert если fail rate >5%)
• ☐ Провести 10-15 тестовых платежей на реальные деньги
• ☐ Проверить что все заказы создаются и уведомления отправляются
• ☐ Проверить что возвраты работают (init refund + webhook confirmation)
• ☐ Задокументировать процесс для support team