ApiPay API v2 Documentation — ApiPay.kz

javascript

import crypto from 'crypto'

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  )
}

// Usage:
// const signature = req.headers['x-webhook-signature']
// const isValid = verifyWebhook(req.rawBody, signature, webhookSecret)

Примеры кода

Создание счёта

JavaScript / Node.js

const response = await fetch('https://bpapi.bazarbay.site/api/v1/invoices', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 10000,
    phone_number: '87001234567',
    description: 'Payment for order #123'
  })
})

const data = await response.json()
console.log('Invoice created:', data.id)

Python

import requests

response = requests.post(
    'https://bpapi.bazarbay.site/api/v1/invoices',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'amount': 10000,
        'phone_number': '87001234567',
        'description': 'Payment for order #123'
    }
)

data = response.json()
print(f"Invoice created: {data['id']}")

PHP

 true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 10000,
        'phone_number' => '87001234567',
        'description' => 'Payment for order #123'
    ]),
    CURLOPT_RETURNTRANSFER => true
]);

$response = json_decode(curl_exec($ch), true);
echo "Invoice created: " . $response['id'];
curl_close($ch);

cURL

curl -X POST https://bpapi.bazarbay.site/api/v1/invoices \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "phone_number": "87001234567",
    "description": "Payment for order #123"
  }'

Создание счёта с корзиной

JavaScript / Node.js

const response = await fetch('https://bpapi.bazarbay.site/api/v1/invoices', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '87001234567',
    description: 'Cart order',
    cart_items: [
      { catalog_item_id: 1, count: 2, price: 4500.00 },
      { catalog_item_id: 5, count: 3 }
    ],
    discount_percentage: 10
  })
})
// Response includes subtotal, discount_sum, discount_percentage

Python

import requests

response = requests.post(
    'https://bpapi.bazarbay.site/api/v1/invoices',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'phone_number': '87001234567',
        'description': 'Cart order',
        'cart_items': [
            {'catalog_item_id': 1, 'count': 2, 'price': 4500.00},
            {'catalog_item_id': 5, 'count': 3}
        ],
        'discount_percentage': 10
    }
)
data = response.json()

PHP

 true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'phone_number' => '87001234567',
        'description' => 'Cart order',
        'cart_items' => [
            ['catalog_item_id' => 1, 'count' => 2, 'price' => 4500.00],
            ['catalog_item_id' => 5, 'count' => 3]
        ],
        'discount_percentage' => 10
    ]),
    CURLOPT_RETURNTRANSFER => true
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

cURL

curl -X POST https://bpapi.bazarbay.site/api/v1/invoices \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "87001234567",
    "description": "Cart order",
    "cart_items": [
      { "catalog_item_id": 1, "count": 2, "price": 4500.00 },
      { "catalog_item_id": 5, "count": 3 }
    ],
    "discount_percentage": 10
  }'

Создание подписки

JavaScript / Node.js

const response = await fetch('https://bpapi.bazarbay.site/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '87001234567',
    amount: 5000,
    billing_period: 'monthly',
    description: 'Monthly subscription'
  })
})
const data = await response.json()
console.log('Subscription:', data.subscription.id)

Python

import requests

response = requests.post(
    'https://bpapi.bazarbay.site/api/v1/subscriptions',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'phone_number': '87001234567',
        'amount': 5000,
        'billing_period': 'monthly',
        'description': 'Monthly subscription'
    }
)
data = response.json()
print(f"Subscription: {data['subscription']['id']}")

PHP

 true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'phone_number' => '87001234567',
        'amount' => 5000,
        'billing_period' => 'monthly',
        'description' => 'Monthly subscription'
    ]),
    CURLOPT_RETURNTRANSFER => true
]);

$response = json_decode(curl_exec($ch), true);
echo "Subscription: " . $response['subscription']['id'];
curl_close($ch);

cURL

curl -X POST https://bpapi.bazarbay.site/api/v1/subscriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "87001234567",
    "amount": 5000,
    "billing_period": "monthly",
    "description": "Monthly subscription"
  }'

Создание подписки с корзиной

JavaScript / Node.js

const response = await fetch('https://bpapi.bazarbay.site/api/v1/subscriptions', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    phone_number: '87001234567',
    billing_period: 'monthly',
    description: 'Monthly cart subscription',
    cart_items: [
      { catalog_item_id: 1, count: 2 },
      { catalog_item_id: 5, count: 1 }
    ]
  })
})
const data = await response.json()

Python

import requests

response = requests.post(
    'https://bpapi.bazarbay.site/api/v1/subscriptions',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'phone_number': '87001234567',
        'billing_period': 'monthly',
        'description': 'Monthly cart subscription',
        'cart_items': [
            {'catalog_item_id': 1, 'count': 2},
            {'catalog_item_id': 5, 'count': 1}
        ]
    }
)
data = response.json()

PHP

 true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'phone_number' => '87001234567',
        'billing_period' => 'monthly',
        'description' => 'Monthly cart subscription',
        'cart_items' => [
            ['catalog_item_id' => 1, 'count' => 2],
            ['catalog_item_id' => 5, 'count' => 1]
        ]
    ]),
    CURLOPT_RETURNTRANSFER => true
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

cURL

curl -X POST https://bpapi.bazarbay.site/api/v1/subscriptions \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "87001234567",
    "billing_period": "monthly",
    "description": "Monthly cart subscription",
    "cart_items": [
      { "catalog_item_id": 1, "count": 2 },
      { "catalog_item_id": 5, "count": 1 }
    ]
  }'

Загрузка изображения и создание товара

JavaScript / Node.js

// Step 1: Upload image
const formData = new FormData()
formData.append('image', imageFile)

const uploadRes = await fetch('https://bpapi.bazarbay.site/api/v1/catalog/upload-image', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  body: formData
})
const { image_id } = await uploadRes.json()

// Step 2: Create product with image
const productRes = await fetch('https://bpapi.bazarbay.site/api/v1/catalog', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    items: [{
      name: 'Coffee Latte',
      selling_price: 1800,
      unit_id: 1,
      image_id
    }]
  })
})

Python

import requests

# Step 1: Upload image
upload_res = requests.post(
    'https://bpapi.bazarbay.site/api/v1/catalog/upload-image',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    files={'image': open('product.jpg', 'rb')}
)
image_id = upload_res.json()['image_id']

# Step 2: Create product with image
product_res = requests.post(
    'https://bpapi.bazarbay.site/api/v1/catalog',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'items': [{
            'name': 'Coffee Latte',
            'selling_price': 1800,
            'unit_id': 1,
            'image_id': image_id
        }]
    }
)

PHP

 true,
    CURLOPT_HTTPHEADER => ['X-API-Key: YOUR_API_KEY'],
    CURLOPT_POSTFIELDS => ['image' => $cfile],
    CURLOPT_RETURNTRANSFER => true
]);
$imageId = json_decode(curl_exec($ch), true)['image_id'];
curl_close($ch);

// Step 2: Create product with image
$ch = curl_init('https://bpapi.bazarbay.site/api/v1/catalog');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'items' => [[
            'name' => 'Coffee Latte',
            'selling_price' => 1800,
            'unit_id' => 1,
            'image_id' => $imageId
        ]]
    ]),
    CURLOPT_RETURNTRANSFER => true
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

cURL

# Step 1: Upload image
IMAGE_ID=$(curl -s -X POST https://bpapi.bazarbay.site/api/v1/catalog/upload-image \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@product.jpg" | jq -r '.image_id')

# Step 2: Create product with image
curl -X POST https://bpapi.bazarbay.site/api/v1/catalog \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"items\": [{
      \"name\": \"Coffee Latte\",
      \"selling_price\": 1800,
      \"unit_id\": 1,
      \"image_id\": \"$IMAGE_ID\"
    }]
  }"

Возврат средств

JavaScript / Node.js

// Full refund
await fetch('https://bpapi.bazarbay.site/api/v1/invoices/42/refund', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ reason: 'Customer request' })
})

// Partial refund
await fetch('https://bpapi.bazarbay.site/api/v1/invoices/42/refund', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ amount: 5000, reason: 'Partial return' })
})

Python

import requests

# Full refund
requests.post(
    'https://bpapi.bazarbay.site/api/v1/invoices/42/refund',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={'reason': 'Customer request'}
)

# Partial refund
requests.post(
    'https://bpapi.bazarbay.site/api/v1/invoices/42/refund',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={'amount': 5000, 'reason': 'Partial return'}
)

PHP

 true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'reason' => 'Customer request'
    ]),
    CURLOPT_RETURNTRANSFER => true
]);
curl_exec($ch);
curl_close($ch);

// Partial refund
$ch = curl_init('https://bpapi.bazarbay.site/api/v1/invoices/42/refund');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 5000,
        'reason' => 'Partial return'
    ]),
    CURLOPT_RETURNTRANSFER => true
]);
curl_exec($ch);
curl_close($ch);

cURL

# Full refund
curl -X POST https://bpapi.bazarbay.site/api/v1/invoices/42/refund \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Customer request"}'

# Partial refund
curl -X POST https://bpapi.bazarbay.site/api/v1/invoices/42/refund \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "reason": "Partial return"}'

Создание QR-счёта

JavaScript / Node.js

const response = await fetch('https://bpapi.bazarbay.site/api/v1/invoices/qr', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 5000,
    description: 'Заказ №123',
    external_order_id: 'order-123'
  })
})

const data = await response.json()
// Покажите QR на экране кассы
document.getElementById('qr').src = data.qr_image_url
// или используйте qr_token_url для своего рендеринга
console.log('QR expires at:', data.qr_expires_at)

Python

import requests

response = requests.post(
    'https://bpapi.bazarbay.site/api/v1/invoices/qr',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'amount': 5000,
        'description': 'Заказ №123',
        'external_order_id': 'order-123'
    }
)

data = response.json()
# Покажите QR на экране кассы: data['qr_image_url']
print(f"QR expires at: {data['qr_expires_at']}")

PHP

 true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 5000,
        'description' => 'Заказ №123',
        'external_order_id' => 'order-123'
    ]),
    CURLOPT_RETURNTRANSFER => true
]);

$response = json_decode(curl_exec($ch), true);
// Покажите QR на экране кассы: $response['qr_image_url']
echo "QR expires at: " . $response['qr_expires_at'];
curl_close($ch);

cURL

curl -X POST https://bpapi.bazarbay.site/api/v1/invoices/qr \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "description": "Заказ №123",
    "external_order_id": "order-123"
  }'

QR-счёт с корзиной

JavaScript / Node.js

const response = await fetch('https://bpapi.bazarbay.site/api/v1/invoices/qr', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    description: 'Заказ №123',
    cart_items: [
      { catalog_item_id: 608400, count: 2, price: 1500 }
    ],
    discount_percentage: 10
  })
})

const data = await response.json()
// data.qr_image_url — готовый PNG, data.qr_token_url — Kaspi-ссылка

Python

import requests

response = requests.post(
    'https://bpapi.bazarbay.site/api/v1/invoices/qr',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'description': 'Заказ №123',
        'cart_items': [
            {'catalog_item_id': 608400, 'count': 2, 'price': 1500}
        ],
        'discount_percentage': 10
    }
)
data = response.json()

PHP

 true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'description' => 'Заказ №123',
        'cart_items' => [
            ['catalog_item_id' => 608400, 'count' => 2, 'price' => 1500]
        ],
        'discount_percentage' => 10
    ]),
    CURLOPT_RETURNTRANSFER => true
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

cURL

curl -X POST https://bpapi.bazarbay.site/api/v1/invoices/qr \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Заказ №123",
    "cart_items": [
      { "catalog_item_id": 608400, "count": 2, "price": 1500 }
    ],
    "discount_percentage": 10
  }'

Проверка номера клиента

JavaScript / Node.js

const response = await fetch('https://bpapi.bazarbay.site/api/v1/clients/check', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ phone: '77001234567' })
})

const data = await response.json()
// { phone: '87001234567', has_kaspi: true, client_name: 'Иван И.' }
if (!data.has_kaspi) {
  // Клиент не зарегистрирован в Kaspi — попросите другой номер
}

Python

import requests

response = requests.post(
    'https://bpapi.bazarbay.site/api/v1/clients/check',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={'phone': '77001234567'}
)

data = response.json()
# {'phone': '87001234567', 'has_kaspi': True, 'client_name': 'Иван И.'}
if not data['has_kaspi']:
    pass  # Клиент не зарегистрирован в Kaspi

PHP

 true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode(['phone' => '77001234567']),
    CURLOPT_RETURNTRANSFER => true
]);

$response = json_decode(curl_exec($ch), true);
// ['phone' => '87001234567', 'has_kaspi' => true, 'client_name' => 'Иван И.']
curl_close($ch);

cURL

curl -X POST https://bpapi.bazarbay.site/api/v1/clients/check \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "77001234567"}'

Коды ошибок

HTTP-статусы (общие для всех эндпоинтов)

Поле «error» при создании счёта (POST /invoices, /invoices/qr)

Поле «error» только для QR-счёта (POST /invoices/qr)

Поле «error» при отмене и возврате

Поле «error» при работе с подписками

Асинхронные ошибки Kaspi: status=error / поле error_message (HTTP-кода нет)

Поле error_code — стабильный машинный код (новое, рекомендуется)

Формат ответа ошибки

{
  "message": "Описание ошибки",
  "errors": {
    "field_name": ["детали ошибки"]
  }
}

Changelog

• 2026-06-11 [new] Вебхуки: добавлены уведомления о неудачных возвратах (invoice.refunded со status=failed и refund.error_code), об ошибках QR-счетов (invoice.status_changed со status=error и error_code: kaspi_session_invalid / kaspi_error / qr_render_failed — дублирует синхронный 5xx-ответ) и о первом частичном возврате (invoice.status_changed со status=partially_refunded). Изменения аддитивные, HMAC-подпись не менялась.
• 2026-06-11 [new] Документация вебхуков актуализирована: добавлены события subscription.created/paused/resumed/cancelled, примеры payload для статусов error/cancelled/failed, разделы «Когда приходит вебхук», «Переходы статусов» (включая легитимные cancelled→paid и error→pending) и «Сценарии реагирования» (что система делает автоматически и что делать интегратору по каждому error_code), описание circuit breaker и ретраев (включая sandbox). Исправлено: даты в вебхуках — UTC; статуса refunded у счёта не существует (полный возврат оставляет paid + is_fully_refunded).
• 2026-06-01 [new] GET /catalog: добавлен опциональный query-параметр statuses[] — фильтр списка товаров по статусу (можно передать несколько значений: active, pending, deleting, failed). Фильтрация выполняется на сервере до пагинации, поэтому meta.total и last_page отражают отфильтрованную выборку. Изменение аддитивное: без параметра поведение прежнее (возвращаются все видимые товары). Статус deleted в выдачу не попадает by design.
• 2026-05-29 [changed] Уточнения в документации по итогам сверки с бэкендом: общий лимит Public API — 200 запросов/мин на API-ключ (при 429 — заголовок Retry-After); лимиты 60 запросов/мин и 10 000 запросов/сутки относятся только к POST /clients/check; POST /invoices/qr — отдельный счётчик 60 QR/мин на организацию (на его 429 заголовка Retry-After нет). Лимит тестовых счетов в sandbox — 500 на организацию. В каталоге error_code для каждого кода размечена синхронность доставки: async (приходит в webhook) либо sync (HTTP-ответ с указанным кодом).
• 2026-05-28 [new] Унификация ошибок: во все JSON-ответы об ошибках и в webhook-объекты invoice (status=error) и refund (status=failed) добавлено новое поле error_code — стабильный snake_case-код из фиксированного каталога (например client_not_found, network_unavailable, kaspi_error, qr_render_failed, kaspi_session_invalid). Изменение аддитивное и обратно совместимое: поля message и error не изменились. Определяйте тип ошибки по error_code, а не по тексту message. error_code в refund-объекте приходит без error_message; HMAC-подпись webhook не менялась.
• 2026-05-28 [new] Webhook invoice.status_changed теперь может содержать два опциональных поля от Kaspi: kaspi_source_type — источник средств клиента (GOLD — дебетовая карта Kaspi, RED — кредитная карта Kaspi, LOAN — рассрочка/кредит, BUSINESSACCOUNT — бизнес-счёт, BANKINTEGRATIONACCOUNT — привязанный внешний банковский счёт) и kaspi_sale_type — способ приёма счёта (Remote — push на номер, QR — QR-код, Restaurant — ресторанный счёт, Static — статичный QR). Обычно приходят при status=paid, но гейтятся по наличию значения, а не строго по статусу: присутствуют, когда Kaspi вернул значение (счёт, уже получивший его, может пробросить поле и в cancelled/expired), и отсутствуют/null иначе — обрабатывайте как nullable. Перечислены известные на сегодня значения; список может расширяться на стороне Kaspi, поэтому обрабатывайте неизвестные значения как «прочее».
• 2026-05-28 [changed] Уточнение по POST /invoices/qr: лимит «один активный QR» считается per-кассир (kaspi_connection_id), а не на всю организацию. Если у организации несколько активных касс, можно показывать разные QR одновременно — на каждую кассу свой. В теле запроса добавлен опциональный kaspi_connection_id — для multi-cashier-организаций (если не указан и >1 активной кассы без primary, вернётся 422 connection_ambiguous). Параллельные запросы на одну и ту же кассу больше не блокируются — race ловится conditional UPDATE; проигравший запрос получает 409 superseded с invoice_id уже отменённого счёта, по этому id придёт webhook со status=cancelled. Дедуплицируйте по (invoice_id + status). В sandbox-режиме scope — per-organization (одна касса). Phone-инвойсы (is_qr_token=false) — TTL 24 часа в Kaspi, не затрагиваются supersede-логикой.
• 2026-05-27 [new] Новый эндпоинт POST /api/v1/clients/check — точечная проверка номера на наличие в Kaspi перед созданием счёта или подписки. Возвращает { phone (нормализованный), has_kaspi, client_name }. Нормализует форматы +7/7/8 и убирает пробелы/дефисы. Не предназначен для массового перебора номеров — на стороне сервера работает детекция аномалий, при срабатывании API-ключ деактивируется без предупреждения, организация блокируется до ручной проверки.
• 2026-05-09 [new] Новый эндпоинт POST /api/v1/invoices/qr — оплата по QR-коду на экране кассы без номера телефона. В ответе qr_token_url (Kaspi-ссылка) и qr_image_url (PNG 600×600 с логотипом Kaspi). TTL — 5 минут. После оплаты прилетает обычный webhook invoice.status_changed (status: paid). Поддерживаются режимы с каталогом (cart_items, discount_percentage) и без (amount). Для sandbox-организаций добавлен опциональный параметр simulate (paid|cancelled|expired) — создаёт счёт сразу в нужном терминальном статусе с мгновенной отправкой webhook (отдельный вызов /simulate-status больше не нужен, но по-прежнему работает).
• 2026-05-01 [changed] Параметр price в cart_items — переопределение цены позиции (если не указан, берётся selling_price из каталога)
• 2026-04-07 [new] Статус processing — счёт создан и ожидает отправки в Kaspi
• 2026-04-07 [new] Статус error и поле error_message — описание ошибки при сбое отправки
• 2026-04-07 [new] Параметр discount_percentage — скидка на весь чек (1-99%)
• 2026-04-07 [new] Параметр bill_immediately — выставить первый счёт подписки сразу
• 2026-04-07 [changed] POST /invoices/{id}/cancel — теперь работает для статусов pending и processing
• 2026-04-07 [new] Ошибки Kaspi-сессии: 400 kaspi_session_not_configured, 503 kaspi_session_invalid
• 2026-04-07 [changed] POST /invoices/status/check — обновлён формат ответа: { invoices: [...] }
• 2026-04-02 [changed] Обновлена API спецификация: удалён GET /status, добавлены новые поля в каталоге (kaspi_item_id, nds_percentage, ntin, synced_at и др.), подписках (billing_period_label, status_label, status_color, paused_at, cancelled_at и др.) и возвратах (organization_id, updated_at), обновлён формат пагинации
• 2026-03-29 [new] Добавлен параметр bill_immediately в POST /subscriptions — немедленное выставление первого счёта при создании подписки
• 2026-03-29 [new] Добавлено поле created_at в ответы эндпоинтов каталога (GET /catalog, POST /catalog) — дата создания товара в системе в формате ISO 8601
• 2026-03-27 [new] Запуск публичной API документации с единым источником правды