Подключение устройства и получение API-ключа

Пошаговая инструкция по подключению Kaspi-терминала через xpayment: OTP-верификация, выпуск API-ключа и устройство.

Что такое устройство?

В xpayment устройство представляет собой подключение к вашей кассе Kaspi Pay. Думайте о нём как о виртуальном терминале, который связывает ваш бизнес-аккаунт Kaspi с платформой xpayment, позволяя принимать онлайн-платежи через наш API.

Каждое добавленное устройство:

Получает собственный API-ключ (xdev_...) для аутентификации
Работает независимо — вы можете управлять несколькими устройствами для разных проектов или окружений
Подключается безопасно без передачи основных учётных данных Kaspi

Зачем нужно устройство

Прежде чем обрабатывать платежи через xpayment, необходимо добавить хотя бы одно устройство. Регистрация устройства:

Устанавливает безопасное соединение между xpayment и вашим аккаунтом Kaspi
Генерирует криптографические ключи для подписи платёжных запросов
Выдаёт API-ключ, который ваше приложение использует для создания платежей

Требования

Для добавления устройства вам понадобится:

Требование	Описание
Аккаунт xpayment	Зарегистрируйтесь в панели управления, если ещё не сделали этого
Аккаунт Kaspi Business	Активный бизнес-аккаунт с включёнными онлайн-платежами
Доступ к телефону	Номер телефона, зарегистрированный в Kaspi для получения OTP-кодов

🔒 Рекомендация по безопасности

Перед подключением устройства создайте выделенную роль кассира в приложении Kaspi Business с минимальными правами. Эта роль должна иметь возможность только:

Принимать платежи

Просматривать собственную историю транзакций

Важно: Роль кассира не может переводить деньги, получать доступ к вашему балансу или управлять вашим аккаунтом. Даже если учётные данные будут скомпрометированы, эта роль не даёт доступа к вашим средствам. Всегда используйте ограниченную роль кассира, никогда не используйте основной административный аккаунт.

Как это работает

Добавление устройства — это простой процесс из 3 шагов в панели управления xpayment:

Добавление устройства: пошаговая инструкция

Регистрация устройства происходит в панели управления xpayment через простой мастер из 3 шагов. Вот что нужно делать на каждом этапе — и что происходит за кулисами.

Шаг 1: Заполнение формы устройства

Перейдите в Устройства → Добавить устройство в панели управления и заполните:

Поле	Описание	Пример
Название устройства	Понятное имя для идентификации устройства	`Касса интернет-магазина`
Номер телефона	Телефон аккаунта Kaspi (должен совпадать с логином кассира)	`+77001234567`
Описание (опционально)	Заметки о назначении устройства	`Боевой терминал основного магазина`

После заполнения формы нажмите Получить OTP-код.

За кулисами:

xpayment генерирует новую пару ключей ECDSA P-256 для устройства
Запрос на регистрацию отправляется в сервис аутентификации Kaspi
Kaspi отправляет 6-значный OTP по SMS на ваш номер телефона
Вы получаете challenge_id внутри системы (действителен 5 минут)

Вы увидите сообщение, подтверждающее отправку OTP. Проверьте телефон для получения SMS-кода.

Шаг 2: Ввод OTP-кода

В течение 5 минут введите 6-значный код, полученный по SMS, в поле OTP-код, затем нажмите Подтвердить.

За кулисами:

xpayment отправляет OTP в Kaspi для проверки
Kaspi подтверждает код и устанавливает криптографическую сессию между xpayment и вашим аккаунтом Kaspi
xpayment сохраняет учётные данные сессии (общий секрет, серийный номер токена)
Создаётся запись UserDevice и связывается с вашим аккаунтом xpayment
Система автоматически генерирует ваш первый API-ключ (xdev_...)

Если OTP неверен или истёк, вы увидите ошибку — в этом случае начните заново с Шага 1.

Шаг 3: Копирование API-ключа

При успешном подтверждении вы увидите экран успеха с отображением API-ключа устройства:

xdev_live_a1b2c3d4e5f6...

⚠️ Критически важно: Сохраните этот ключ немедленно!

Этот ключ показывается только один раз при создании устройства. xpayment хранит только SHA-256 хеш ключа, поэтому мы не можем восстановить его позже. Если вы потеряете его, вам нужно будет сгенерировать новый ключ.

Что делать с ключом:

Скопируйте полное значение ключа
Сохраните безопасно в переменных окружения бэкенда (например, файл .env или менеджер секретов)
Никогда не коммитьте его в систему контроля версий и не размещайте в клиентском коде

Что вы создали

После завершения настройки ваш аккаунт xpayment теперь имеет:

Ресурс	Детали
Устройство	Зарегистрированный терминал Kaspi Pay с криптографическими ключами подписи
Активная сессия	Постоянное безопасное соединение с Kaspi для подписи платёжных запросов
API-ключ	Учётные данные для аутентификации в формате `xdev_live_...`

Устройство теперь готово обрабатывать платежи. Вы можете просмотреть его в списке устройств, где увидите:

Название и описание устройства
Дату создания
Количество активных API-ключей
Статус сессии (активна/истекла)

Управление устройствами и ключами

Создание дополнительных API-ключей

Вы можете генерировать несколько API-ключей для одного устройства (полезно для разных окружений или ротации ключей):

Перейдите в Устройства → выберите ваше устройство
Нажмите Создать новый ключ
Дайте ключу имя (например, Тестовое окружение)
Немедленно скопируйте и сохраните новый ключ

Отзыв ключа

Если ключ скомпрометирован или больше не нужен:

Найдите ключ в списке ключей устройства
Нажмите Отозвать
Подтвердите действие

Отозванные ключи перестают работать немедленно. Любые платёжные запросы с использованием отозванного ключа будут отклонены с ошибкой 401 Unauthorized.

Поддержка сессии

xpayment автоматически поддерживает вашу сессию Kaspi активной через периодические keepalive-запросы. Если сессия истекает (обычно после 30 дней бездействия), вы увидите предупреждение в панели управления. Просто перерегистрируйте устройство, чтобы обновить сессию.

Прямые платежи — списание с клиента по номеру телефона одним API-вызовом
Платёжные ссылки с QR — генерация QR-кода, который клиенты сканируют для оплаты

Использование вашего устройства в приложении

Теперь, когда у вас есть устройство и его API-ключ, вы можете начать принимать платежи в своём приложении. В этом разделе показано, как интегрировать ключ и делать платёжные запросы.

Быстрый старт: Ваш первый платёжный запрос

Вот минимальный пример создания платежа с использованием API-ключа устройства:

curl -X POST https://api.xpayment.com/v1/payments \
  -H "Authorization: Bearer xdev_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "KZT",
    "order_id": "order-12345",
    "description": "Premium subscription",
    "return_url": "https://yourstore.com/payment/complete",
    "metadata": {
      "customer_id": "cust_001"
    }
  }'

Ответ:

{
  "id": "pay_xyz789",
  "status": "pending",
  "amount": 5000,
  "currency": "KZT",
  "order_id": "order-12345",
  "payment_url": "https://kaspi.kz/pay/qr?token=...",
  "qr_code_url": "https://api.xpayment.com/v1/payments/pay_xyz789/qr",
  "expires_at": "2026-04-10T12:15:00Z",
  "created_at": "2026-04-10T12:00:00Z"
}

Ваш клиент использует payment_url или сканирует QR-код по адресу qr_code_url для завершения платежа в приложении Kaspi.

Примеры интеграции

Node.js / Express

import axios from 'axios';

const XPAYMENT_API_KEY = process.env.XPAYMENT_DEVICE_KEY; // xdev_live_...
const XPAYMENT_BASE_URL = 'https://api.xpayment.com/v1';

const client = axios.create({
  baseURL: XPAYMENT_BASE_URL,
  headers: {
    'Authorization': `Bearer ${XPAYMENT_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

async function createPayment(orderData) {
  const response = await client.post('/payments', {
    amount: orderData.totalCents,
    currency: 'KZT',
    order_id: orderData.orderId,
    description: orderData.itemDescription,
    return_url: `https://mystore.com/orders/${orderData.orderId}/complete`,
    metadata: {
      customer_email: orderData.customerEmail,
    },
  });

  return response.data; // { id, payment_url, qr_code_url, ... }
}

// Usage
const payment = await createPayment({
  orderId: 'ORD-12345',
  totalCents: 15000, // 150.00 KZT
  itemDescription: 'Order #12345',
  customerEmail: '[email protected]',
});

console.log('Payment URL:', payment.payment_url);
console.log('QR Code:', payment.qr_code_url);

Python / Flask

import os
import requests

XPAYMENT_API_KEY = os.environ['XPAYMENT_DEVICE_KEY']  # xdev_live_...
XPAYMENT_BASE_URL = 'https://api.xpayment.com/v1'

headers = {
    'Authorization': f'Bearer {XPAYMENT_API_KEY}',
    'Content-Type': 'application/json',
}

def create_payment(order_data):
    response = requests.post(
        f'{XPAYMENT_BASE_URL}/payments',
        headers=headers,
        json={
            'amount': order_data['total_cents'],
            'currency': 'KZT',
            'order_id': order_data['order_id'],
            'description': order_data['description'],
            'return_url': f"https://mystore.com/orders/{order_data['order_id']}/complete",
            'metadata': {
                'customer_email': order_data['customer_email'],
            },
        },
    )
    response.raise_for_status()
    return response.json()

# Usage
payment = create_payment({
    'order_id': 'ORD-12345',
    'total_cents': 15000,  # 150.00 KZT
    'description': 'Order #12345',
    'customer_email': '[email protected]',
})

print(f"Payment URL: {payment['payment_url']}")
print(f"QR Code: {payment['qr_code_url']}")

PHP / Laravel

<?php

use Illuminate\Support\Facades\Http;

$apiKey = env('XPAYMENT_DEVICE_KEY'); // xdev_live_...
$baseUrl = 'https://api.xpayment.com/v1';

function createPayment(array $orderData) {
    global $apiKey, $baseUrl;

    $response = Http::withHeaders([
        'Authorization' => 'Bearer ' . $apiKey,
        'Content-Type' => 'application/json',
    ])->post("{$baseUrl}/payments", [
        'amount' => $orderData['total_cents'],
        'currency' => 'KZT',
        'order_id' => $orderData['order_id'],
        'description' => $orderData['description'],
        'return_url' => "https://mystore.com/orders/{$orderData['order_id']}/complete",
        'metadata' => [
            'customer_email' => $orderData['customer_email'],
        ],
    ]);

    return $response->json();
}

// Usage
$payment = createPayment([
    'order_id' => 'ORD-12345',
    'total_cents' => 15000, // 150.00 KZT
    'description' => 'Order #12345',
    'customer_email' => '[email protected]',
]);

echo "Payment URL: {$payment['payment_url']}\n";
echo "QR Code: {$payment['qr_code_url']}\n";

Ключевые моменты для интеграции

Тема	Детали
Аутентификация	Используйте Bearer схему: `Authorization: Bearer xdev_live_...`
Окружение	Храните ключ в переменных окружения, никогда не хардкодьте его
Формат ключа	`xdev_live_...` для production, `xdev_test_...` для sandbox (когда станет доступен)
Базовый URL	`https://api.xpayment.com/v1`
Content Type	Всегда используйте `application/json`

Несколько устройств: Если у вас несколько касс или проектов — просто добавьте отдельное устройство через панель для каждой точки. Каждое устройство имеет свой API-ключ, который используется независимо.