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')
  const got = Buffer.from(signature || '')
  const exp = Buffer.from(expected)
  if (got.length !== exp.length) return false
  return crypto.timingSafeEqual(exp, got)
}

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

Примеры кода

Симуляция статуса (sandbox)

JavaScript / Node.js

// Только для sandbox-счёта (is_sandbox: true) в статусе pending.
const res = await fetch('https://api.apipay.kz/api/v1/invoices/42/simulate-status', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_SANDBOX_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ status: 'paid' })
  // status: 'error' -> error_code: sandbox_simulated_error (+ optional error_message)
  // status: 'qr_scanned' -> только для QR-счёта, статус остаётся pending
})
const data = await res.json()
console.log('Simulated:', data.invoice.status)

Python

import requests

# Только для sandbox-счёта (is_sandbox: true) в статусе pending.
res = requests.post(
    'https://api.apipay.kz/api/v1/invoices/42/simulate-status',
    headers={'X-API-Key': 'YOUR_SANDBOX_API_KEY', 'Content-Type': 'application/json'},
    json={'status': 'paid'}
)
print('Simulated:', res.json()['invoice']['status'])

cURL

# Только для sandbox-счёта (is_sandbox: true) в статусе pending.
curl -X POST https://api.apipay.kz/api/v1/invoices/42/simulate-status \
  -H "X-API-Key: YOUR_SANDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

Проверка доставки вебхука

JavaScript / Node.js

// Убедиться, что по счёту 42 ушёл вебхук и приёмник ответил 2xx.
const res = await fetch(
  'https://api.apipay.kz/api/v1/webhook-logs?invoice_id=42&event=invoice.status_changed',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
)
const { data } = await res.json()
const delivered = data.some(l => l.status === 'success')
console.log('Webhook delivered:', delivered)

Python

import requests

# Убедиться, что по счёту 42 ушёл вебхук и приёмник ответил 2xx.
res = requests.get(
    'https://api.apipay.kz/api/v1/webhook-logs',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    params={'invoice_id': 42, 'event': 'invoice.status_changed'}
)
logs = res.json()['data']
print('Webhook delivered:', any(l['status'] == 'success' for l in logs))

cURL

# Убедиться, что по счёту 42 ушёл вебхук и приёмник ответил 2xx.
curl "https://api.apipay.kz/api/v1/webhook-logs?invoice_id=42&event=invoice.status_changed" \
  -H "X-API-Key: YOUR_API_KEY"

Проверка доставки вебхука каталога

JavaScript / Node.js

// Проверить, что позиция каталога 12345 обработана и вебхук ушёл.
const res = await fetch(
  'https://api.apipay.kz/api/v1/catalog/webhook-logs?catalog_item_id=12345&status=success',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
)
const { data } = await res.json()
console.log('Deliveries:', data.length)

Python

import requests

# Проверить, что позиция каталога 12345 обработана и вебхук ушёл.
res = requests.get(
    'https://api.apipay.kz/api/v1/catalog/webhook-logs',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    params={'catalog_item_id': 12345, 'status': 'success'}
)
logs = res.json()['data']
print('Deliveries:', len(logs))

cURL

# Проверить, что позиция каталога 12345 обработана и вебхук ушёл.
curl "https://api.apipay.kz/api/v1/catalog/webhook-logs?catalog_item_id=12345&status=success" \
  -H "X-API-Key: YOUR_API_KEY"

Идемпотентная bulk-заливка каталога (Idempotency-Key + батч)

JavaScript / Node.js

// Повтор с тем же Idempotency-Key вернёт существующий батч (200) без пересоздания.
const res = await fetch('https://api.apipay.kz/api/v1/catalog', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
    'Idempotency-Key': 'import-2026-07-11-0001'
  },
  body: JSON.stringify({
    items: [
      { name: 'Фильтр масляный', selling_price: 1800, unit_id: 1, external_ref: '1C-000123' }
    ]
    // альтернатива заголовку: idempotency_key: 'import-2026-07-11-0001'
  })
})
const { batch } = await res.json()
console.log('Batch:', batch?.batch_id, batch?.poll_url)

Python

import requests

# Повтор с тем же Idempotency-Key вернёт существующий батч (200) без пересоздания.
res = requests.post(
    'https://api.apipay.kz/api/v1/catalog',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Idempotency-Key': 'import-2026-07-11-0001',
    },
    json={
        'items': [
            {'name': 'Фильтр масляный', 'selling_price': 1800, 'unit_id': 1, 'external_ref': '1C-000123'}
        ]
    },
)
batch = res.json().get('batch') or {}
print('Batch:', batch.get('batch_id'), batch.get('poll_url'))

cURL

# Повтор с тем же Idempotency-Key вернёт СУЩЕСТВУЮЩИЙ батч (HTTP 200) без пересоздания.
curl -X POST https://api.apipay.kz/api/v1/catalog \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-07-11-0001" \
  -d '{
    "items": [
      { "name": "Фильтр масляный", "selling_price": 1800, "unit_id": 1, "external_ref": "1C-000123" }
    ]
  }'
# В ответе (202/200) — блок batch с batch_id и poll_url.
# Прогресс: GET https://api.apipay.kz/api/v1/catalog/batches/8f14e45f-ceea-467e-9a2c-0000000000aa
# Фильтр списка по батчу: GET https://api.apipay.kz/api/v1/catalog?batch_id=8f14e45f-ceea-467e-9a2c-0000000000aa

Остаток очереди приёма каталога + ETA

JavaScript / Node.js

// Остаток pending-очереди приёма каталога с блоком queue (ETA в минутах).
const res = await fetch('https://api.apipay.kz/api/v1/catalog/queue?sort_order=asc&per_page=100', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
const { total, queue } = await res.json()
console.log('Remaining:', total, 'ETA min:', queue?.eta_minutes, 'state:', queue?.state)

Python

import requests

# Остаток pending-очереди приёма каталога с блоком queue (ETA в минутах).
res = requests.get(
    'https://api.apipay.kz/api/v1/catalog/queue',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    params={'sort_order': 'asc', 'per_page': 100},
)
body = res.json()
print('Remaining:', body['total'], 'ETA min:', body['queue'].get('eta_minutes'))

cURL

# Остаток pending-очереди приёма каталога со слим-полями и блоком queue (ETA в минутах).
curl "https://api.apipay.kz/api/v1/catalog/queue?sort_order=asc&per_page=100" \
  -H "X-API-Key: YOUR_API_KEY"
# Ответ: { current_page, data:[{id, external_ref, name, queued_at}], total, queue:{ state, eta_minutes, ... } }

Журнал ошибок приёма каталога

JavaScript / Node.js

// Failed-позиции по конкретному батчу (обезличенные тексты ошибок).
const res = await fetch(
  'https://api.apipay.kz/api/v1/catalog/errors?batch_id=8f14e45f-ceea-467e-9a2c-0000000000aa&per_page=100',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
)
const { data } = await res.json()
data.forEach((e) => console.log(e.external_ref, e.error_code, e.error_message))

Python

import requests

# Failed-позиции по конкретному батчу (обезличенные тексты ошибок).
res = requests.get(
    'https://api.apipay.kz/api/v1/catalog/errors',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    params={'batch_id': '8f14e45f-ceea-467e-9a2c-0000000000aa', 'per_page': 100},
)
for e in res.json()['data']:
    print(e['external_ref'], e['error_code'], e['error_message'])

cURL

# Failed-позиции по конкретному батчу (обезличенные тексты ошибок).
curl "https://api.apipay.kz/api/v1/catalog/errors?batch_id=8f14e45f-ceea-467e-9a2c-0000000000aa&per_page=100" \
  -H "X-API-Key: YOUR_API_KEY"
# Без batch_id и from — окно последних 7 дней по created_at.

Прогресс bulk-батча приёма каталога

JavaScript / Node.js

// Агрегированный прогресс батча (poll до pending_remaining == 0).
const res = await fetch(
  'https://api.apipay.kz/api/v1/catalog/batches/8f14e45f-ceea-467e-9a2c-0000000000aa',
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
)
const b = await res.json()
console.log(b.status, b.totals, 'left:', b.pending_remaining)

Python

import requests

# Агрегированный прогресс батча (poll до pending_remaining == 0).
res = requests.get(
    'https://api.apipay.kz/api/v1/catalog/batches/8f14e45f-ceea-467e-9a2c-0000000000aa',
    headers={'X-API-Key': 'YOUR_API_KEY'},
)
b = res.json()
print(b['status'], b['totals'], 'left:', b['pending_remaining'])

cURL

# Агрегированный прогресс батча (poll до pending_remaining == 0).
curl "https://api.apipay.kz/api/v1/catalog/batches/8f14e45f-ceea-467e-9a2c-0000000000aa" \
  -H "X-API-Key: YOUR_API_KEY"
# Чужой/несуществующий/битый UUID → 404 (non-enumeration).

Автономный тест без человека (полный цикл)

cURL

# Полный автономный цикл для ИИ-агента с sandbox-ключом (X-API-Key).
# Критерий успеха: каждый шаг подтверждается записью в /webhook-logs.
KEY="YOUR_SANDBOX_API_KEY"
BASE="https://api.apipay.kz/api/v1"

# 1. Создать sandbox-счёт (external_order_id_idempotency защищает от дублей при ретрае).
INVOICE_ID=$(curl -s -X POST "$BASE/invoices" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "phone_number": "87770000001",
    "amount": 5000,
    "description": "Autotest order",
    "external_order_id_idempotency": "autotest-001"
  }' | jq -r '.id')

# 1a. Дождаться статуса pending — счёт создаётся в processing, переход
#     асинхронный (обычно 1-3 секунды). simulate-status требует pending.
#     (QR-счёт из POST /invoices/qr сразу pending — для него шаг не нужен.)
until [ "$(curl -s "$BASE/invoices/$INVOICE_ID" -H "X-API-Key: $KEY" | jq -r '.status')" = "pending" ]; do
  sleep 1
done

# 2. Перевести счёт в paid (симуляция оплаты, только sandbox).
curl -s -X POST "$BASE/invoices/$INVOICE_ID/simulate-status" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

# 3. Убедиться, что ушёл вебхук invoice.status_changed (status=paid).
#    Совет: если ответ пуст — проверьте по ?invoice_id=$INVOICE_ID без event;
#    тип события есть в request_body записи.
curl -s "$BASE/webhook-logs?invoice_id=$INVOICE_ID&event=invoice.status_changed" \
  -H "X-API-Key: $KEY" | jq '.data[] | {event, status, response_status}'

# 4. Частичный возврат (в песочнице проходит без Kaspi; статус paid -> partially_refunded).
curl -s -X POST "$BASE/invoices/$INVOICE_ID/refund" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{ "amount": 2000 }'

# 5. Проверить вебхуки возврата: invoice.refunded + invoice.status_changed (partially_refunded).
curl -s "$BASE/webhook-logs?invoice_id=$INVOICE_ID" \
  -H "X-API-Key: $KEY" | jq '.data[] | {event, status}'

# Ветки других статусов (каждый — новый sandbox-счёт, дождаться pending как в шаге 1a):
#   simulate-status { "status": "cancelled" }  -> invoice.status_changed (cancelled)
#   simulate-status { "status": "expired" }    -> invoice.status_changed (expired)
#   simulate-status { "status": "error", "error_message": "..." }
#                                              -> error_code: sandbox_simulated_error
# QR-счёт: POST /invoices/qr с телом { "amount": 5000, "description": "QR autotest" }
#   (phone_number не нужен; счёт сразу pending) + simulate-status { "status": "qr_scanned" }:
#   -> invoice.qr_scanned (qr_substate=scanned, статус остаётся pending)
#
# Sandbox-вебхуки: 3 попытки, backoff 5с/15с. Успех = любой HTTP 2xx.

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

JavaScript / Node.js

const response = await fetch('https://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/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://api.apipay.kz/api/v1/clients/check \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "77001234567"}'

Превью фискального чека

JavaScript / Node.js

const res = await fetch('https://api.apipay.kz/api/v1/receipts/preview', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ payment_type: 3, total_price: 10 })
})
const { data } = await res.json()
console.log('Preview lines:', data)

Python

import requests

res = requests.post(
    'https://api.apipay.kz/api/v1/receipts/preview',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={'payment_type': 3, 'total_price': 10}
)
lines = res.json()['data']
print('Preview lines:', lines)

PHP

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

$response = json_decode(curl_exec($ch), true);
// $response['data'] — строки превью чека
curl_close($ch);

cURL

# Синхронное превью строк чека для UI. payment_type: 3 — наличные, 5 — POS другого банка.
curl -X POST https://api.apipay.kz/api/v1/receipts/preview \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_type": 3,
    "total_price": 10
  }'
# 200 → { "data": [ { "Title": "Способ оплаты", "Subtitle": "Наличные", "isBoldText": false } ] }

Выбить фискальный чек

JavaScript / Node.js

const res = await fetch('https://api.apipay.kz/api/v1/receipts', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_type: 3,
    client_operation_id: 'pos-cash-0042',
    received_amt: 5000,
    cart_items: [
      { catalog_item_id: 1, quantity: 2, price: 1800 },
      { catalog_item_id: 5, quantity: 1 }
    ]
  })
})
const receipt = await res.json()
// 202 pending → опрашивайте GET /receipts/{id} или ждите вебхук
console.log('Receipt queued:', receipt.id, receipt.status)

Python

import requests

res = requests.post(
    'https://api.apipay.kz/api/v1/receipts',
    headers={
        'X-API-Key': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'payment_type': 3,
        'client_operation_id': 'pos-cash-0042',
        'received_amt': 5000,
        'cart_items': [
            {'catalog_item_id': 1, 'quantity': 2, 'price': 1800},
            {'catalog_item_id': 5, 'quantity': 1}
        ]
    }
)
receipt = res.json()
print('Receipt queued:', receipt['id'], receipt['status'])

PHP

 true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_API_KEY',
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'payment_type' => 3,
        'client_operation_id' => 'pos-cash-0042',
        'received_amt' => 5000,
        'cart_items' => [
            ['catalog_item_id' => 1, 'quantity' => 2, 'price' => 1800],
            ['catalog_item_id' => 5, 'quantity' => 1]
        ]
    ]),
    CURLOPT_RETURNTRANSFER => true
]);

$response = json_decode(curl_exec($ch), true);
// 202 → $response['id'], $response['status'] === 'pending'
curl_close($ch);

cURL

# Асинхронно выбивает чек в Kaspi OFD. Позиции — из каталога по catalog_item_id
# (только фискальные, с НТИН). client_operation_id — ключ идемпотентности.
# received_amt — наличные, полученные от клиента (для сдачи).
curl -X POST https://api.apipay.kz/api/v1/receipts \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_type": 3,
    "client_operation_id": "pos-cash-0042",
    "received_amt": 5000,
    "cart_items": [
      { "catalog_item_id": 1, "quantity": 2, "price": 1800 },
      { "catalog_item_id": 5, "quantity": 1 }
    ]
  }'
# 202 → { "id": 4210, "status": "pending", "client_operation_id": "pos-cash-0042" }
# Итог узнайте через GET https://api.apipay.kz/api/v1/receipts/4210 или вебхук receipt.issued/receipt.failed.

Статус фискального чека

JavaScript / Node.js

const res = await fetch('https://api.apipay.kz/api/v1/receipts/4210', {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
const receipt = await res.json()
if (receipt.status === 'issued') {
  console.log('Receipt link:', receipt.link, 'FPD:', receipt.fpd)
} else if (receipt.status === 'failed') {
  console.log('Failed:', receipt.error_code)
}

Python

import requests

res = requests.get(
    'https://api.apipay.kz/api/v1/receipts/4210',
    headers={'X-API-Key': 'YOUR_API_KEY'}
)
receipt = res.json()
if receipt['status'] == 'issued':
    print('Receipt link:', receipt['link'], 'FPD:', receipt['fpd'])
elif receipt['status'] == 'failed':
    print('Failed:', receipt['error_code'])

PHP

 ['X-API-Key: YOUR_API_KEY'],
    CURLOPT_RETURNTRANSFER => true
]);

$receipt = json_decode(curl_exec($ch), true);
// $receipt['status']: 'pending' | 'issued' | 'failed'
curl_close($ch);

cURL

# Поллинг статуса чека: pending | issued | failed.
curl "https://api.apipay.kz/api/v1/receipts/4210" \
  -H "X-API-Key: YOUR_API_KEY"
# issued → { "status": "issued", "fpd": "000000000000",
#   "operation_id": "KKM00000000", "link": "https://receipt.kaspi.kz/...",
#   "shift_number": 106 }

История фискальных чеков

JavaScript / Node.js

// Чеки за календарный день мерчанта (Asia/Almaty): голая дата включает весь день.
const params = new URLSearchParams({
  from: '2026-07-14',
  to: '2026-07-14',
  status: 'issued',
  per_page: '20',
})
const res = await fetch(`https://api.apipay.kz/api/v1/receipts?${params}`, {
  headers: { 'X-API-Key': 'YOUR_API_KEY' }
})
const { data, total } = await res.json()
data.forEach((r) => console.log(r.id, r.status, r.total_price, r.link))
console.log('total:', total)

Python

import requests

# Чеки за календарный день мерчанта (Asia/Almaty): голая дата включает весь день.
res = requests.get(
    'https://api.apipay.kz/api/v1/receipts',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    params={'from': '2026-07-14', 'to': '2026-07-14', 'status': 'issued', 'per_page': 20},
)
body = res.json()
for r in body['data']:
    print(r['id'], r['status'], r['total_price'], r['link'])
print('total:', body['total'])

cURL

# Чеки за календарный день мерчанта (Asia/Almaty): голая дата включает весь день.
curl "https://api.apipay.kz/api/v1/receipts?from=2026-07-14&to=2026-07-14&status=issued&per_page=20" \
  -H "X-API-Key: YOUR_API_KEY"
# Плоская пагинация: { "current_page": 1, "data": [...], "total": 12 }.
# Чтение истории не гейтится kill-switch'ем — список доступен всегда.

Коды ошибок

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

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

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

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

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

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

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

Каталог: резолв штрихкода (POST /catalog/scan)

KYC: верификация бизнеса и webhook-домен (новое)

Фискальные чеки (Kaspi OFD)

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

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

Changelog

• 2026-07-22 [changed] Ошибка 403 tariff_inactive (нет действующей подписки на ApiPay) теперь закрывает ВСЕ платные операции, а не только создание счёта и чека: отмену и возврат счёта, весь изменяющий каталог (создание, изменение, удаление, повтор, scan, sync, загрузка изображения), создание, изменение и возобновление подписок, POST /organizations/{id}/sync и проверку номера клиента. Грейс-период отменён — блокировка наступает сразу после expires_at, а не через 3 дня. В теле 403 добавлено поле expires_at (ISO 8601) — когда истёк тариф; null, если тариф не оформлялся ни разу. Продолжают работать: все операции чтения (GET), оплата тарифа, управление ключами, менеджерами и настройками организации, подключение и переподключение кассира, проверка статусов счетов, а также приостановка и отмена подписок. Отдельно: POST /invoices/bulk при неактивном тарифе отбивает весь запрос 403, а не возвращает 201 с tariff_inactive в поэлементном invoices[]. Песочница и тестовые организации не блокируются вовсе — тариф там не требуется.
• 2026-07-14 [new] Появился GET /receipts — история фискальных чеков организации: пагинированный список (свежие сверху), плоская пагинация {current_page, data, total}, элемент списка той же формы, что отдаёт GET /receipts/{id}. Фильтры: status (pending | issued | failed), payment_type (3 — наличные, 5 — POS другого банка), invoice_id, окно дат from / to. Чтение истории НЕ гейтится kill-switch'ем fiscal_receipts_disabled (он про выбивание чека): даже с выключенной фичей список уже выбитых чеков остаётся доступен. Выборка скоупится режимом организации — боевая организация не видит чеки песочницы, и наоборот. per_page — от 1 до 100 (по умолчанию 20). Окно дат from / to трактуется в Asia/Almaty (+05:00): голая дата (2026-07-14) — это календарные сутки мерчанта, а to включает весь день целиком; дата-время с явным смещением берётся как есть. Компенсировать смещение на клиенте не нужно. То же правило окна дат теперь действует и у GET /catalog/errors. Изменение аддитивное.
• 2026-07-13 [changed] Песочница фискальных чеков теперь зеркалит рабочий режим и доступна независимо от постепенного включения фичи в бою: kill-switch (403 fiscal_receipts_disabled) гейтит только боевые организации, в песочнице чеки работают всегда. Позиция каталога фискальна, только если у неё есть И штрихкод (barcode), И НТИН Нацкаталога (ntin): такая позиция даёт issued с реальными суммами, а позиция без НТИН — failed / item_not_fiscal, ровно как в бою (раньше sandbox-чек молча выходил пустым на 0 ₸). В POST /receipts добавлено поле simulate — только для sandbox-организаций: {"simulate": {"status": "failed", "error_code": "shift_closed"}} форсирует исход чека, чтобы обкатать обработку ошибок (error_code — shift_closed | item_not_fiscal | receipt_kaspi_error, по умолчанию receipt_kaspi_error; status — issued | failed). На боевой организации simulate возвращает 403 not_sandbox, чек не создаётся. Вебхуки receipt.issued / receipt.failed в песочнице уходят независимо от прод-флага вебхуков — доставку можно проверить через GET /webhook-logs?event=receipt.failed. Изменение аддитивное.
• 2026-07-12 [changed] Базовый URL API изменён на https://api.apipay.kz/api/v1 (партнёрский — https://api.apipay.kz/api/partner). Обновите базовый адрес в своих интеграциях.
• 2026-07-12 [new] Новая группа эндпоинтов «Фискальные чеки» (Kaspi OFD) для оплат, НЕ прошедших через Kaspi QR — наличными (payment_type=3) и через POS другого банка (payment_type=5): POST /receipts/preview (синхронное превью строк чека для UI), POST /receipts (асинхронно выбивает чек) и GET /receipts/{id} (статус и реквизиты — fpd, operation_id, link, shift_number). Модель асинхронная: чек создаётся в статусе pending и переходит в issued или failed — итог узнавайте поллингом GET /receipts/{id} либо вебхуком receipt.issued / receipt.failed. Идемпотентность по client_operation_id (уникален на организацию): повтор с тем же ключом не выбивает второй чек (409 duplicate_client_operation_id); повтор после failed разрешён с НОВЫМ ключом. Позиции — из синхронизированного каталога по catalog_item_id, только фискально зарегистрированные (с НТИН), иначе item_not_fiscal. Фича за kill-switch: при отключении отдаётся 403 fiscal_receipts_disabled; включается постепенно. Изменение аддитивное.
• 2026-07-12 [new] GET /catalog: добавлен фильтр without_ntin. При without_ntin=true возвращаются только позиции без НТИН (ntin = null), независимо от наличия штрихкода — шире, чем поле ответа ntin_missing (оно требует непустой barcode). Удобно считать «сколько осталось доделать» по meta.total. Компонуется со всеми режимами и фильтрами (statuses[], search и т.д.). Изменение аддитивное.
• 2026-07-11 [new] Новый эндпоинт GET /catalog/queue — остаток pending-очереди приёма каталога (POST /catalog) со слим-полями плюс блок queue с ETA в минутах. ETA учитывает общую FIFO-очередь кассира. Плоская пагинация {current_page, data, total, queue}; параметры sort_order (по умолчанию asc), per_page (20–100), page. Rate-limit 600/min на ключ (выделенный catalog-poll).
• 2026-07-11 [new] Новый эндпоинт GET /catalog/errors — журнал ошибок приёма каталога (failed-позиции) с обезличенными текстами ошибок. Фильтр по периоду постановки в очередь (created_at); без from — окно последних 7 дней. Параметры from, to, batch_id, sort_order (по умолчанию desc), per_page (20–100), page. Плоская пагинация {current_page, data, total}. Rate-limit 600/min на ключ.
• 2026-07-11 [new] Новый эндпоинт GET /catalog/batches/{id} — агрегированный прогресс bulk-батча приёма каталога (totals: total/created/updated/skipped/failed, pending_remaining, poll_url, статус). Скоуп строго по организации ключа: чужой/несуществующий/битый UUID → 404 (non-enumeration). Итог батча также приходит вебхуком catalog.batch_processed. Rate-limit 600/min на ключ.
• 2026-07-11 [changed] POST /catalog: bulk-приём стал идемпотентным — заголовок Idempotency-Key (или body-поле idempotency_key, ≤191): повтор с тем же ключом возвращает существующий батч (HTTP 200) без пересоздания позиций. В ответы добавлен блок batch (агрегат bulk-батча + poll_url; в 202 — только на инжест-пути). В GET /catalog добавлен фильтр ?batch_id= (по last_batch_id, компонуется со всеми режимами). Новый вебхук catalog.batch_processed — один агрегированный итог bulk-заливки вместо лавины per-item (дедуп по batch_id+status; sample_failed до 50 позиций без текста ошибки).
• 2026-07-09 [new] Новый эндпоинт GET /catalog/webhook-logs — read-only логи доставок вебхука catalog.item_processed вашей организации (отдельная таблица, ротация 3 дня). Плоская пагинация {current_page, data, total}; фильтры status, catalog_item_id, created_after, sort_order, per_page, page.
• 2026-07-09 [changed] POST /catalog переведён на match-and-merge: совпадение позиции с существующим товаром возвращает его живой id с маркером matched_existing: true (без дублей), маркер name_differs: true — если совпал barcode/НТИН, но имя другое (имя не перезаписано). external_ref — ключ маппинга (UNIQUE per org, не перетирается), повторная заливка идемпотентна. Новый ответ 409 error_code catalog_busy — каталог занят другой операцией, повторите запрос.
• 2026-07-09 [changed] GET /catalog: по умолчанию во всех режимах отдаётся только статус active — прочие статусы запрашивайте явно через statuses[]. Призраки (deleted без kaspi_item_id) не отдаются никогда. Targeted-режим: суммарно ≤200 значений по всем наборам и ≤1000 строк соответствий, превышение → 422 error_code catalog_match_overflow (тихого усечения limit(200) больше нет).
• 2026-07-09 [changed] Схема товара каталога (CatalogItem) дополнена полями: ntin_missing (есть barcode, но нет НТИН → не попадёт в фискальный чек как маркированный; присутствует во всех ответах), matched_existing и name_differs (только в ответе POST /catalog). Все изменения аддитивные.
• 2026-07-07 [new] Многоуровневая верификация бизнеса (tiered KYC). Молодая организация проходит короткую анкету «Расскажите о бизнесе» (кабинет, /business-profile). Пока анкета не одобрена, в рабочем режиме доступен 1 реальный счёт в сутки (окно Asia/Almaty; песочница без ограничений) — при превышении HTTP 429 error_code kyc_daily_limit_reached (meta.reset_at, meta.kyc_status). По итогам проверки организация может быть заблокирована — создание счёта тогда отдаёт HTTP 403 error_code kyc_rejected. Для ещё не одобренных организаций в рабочем режиме адрес webhook должен быть на вашем домене: IP → HTTP 422 webhook_url_requires_domain, туннели (ngrok и подобные) → HTTP 422 webhook_url_tunnel_forbidden (в песочнице правила мягче). Все изменения аддитивные. Зачем это нужно: проверка снижает риск блокировки легитимного продавца антифродом и позволяет настроить лимиты под ваши обороты.
• 2026-07-06 [new] Документация /docs выровнена с кодом. Добавлены разделы: Quickstart «первый счёт за 5 минут», Rate-лимиты (полная таблица), Идемпотентность и ретраи, QR-счета: жизненный цикл (событие invoice.qr_scanned), Мультикассир (/connections* с гейтом can_manage_cashiers), Тариф и здоровье аккаунта (GET /tariff, /tariff/plans, /account/health), Bulk-счета (POST /invoices/bulk, до 100, лимит 20/мин), Sandbox (магические номера, simulate-*). Каталог error_code дополнен антифрод-кодами (outstanding_recipient_limit, outstanding_org_limit, trial_daily_limit — 429 + Retry-After). Все изменения аддитивные.
• 2026-07-06 [new] Автономное тестирование для ИИ-агентов: sandbox-агент с API-ключом теперь проходит полный цикл создание счёта → изменение статуса → проверка вебхука без человека. (1) POST /api/v1/invoices/{id}/simulate-status расширен: помимо paid/cancelled/expired добавлены значения error (счёт получает error_code: sandbox_simulated_error и опциональный error_message до 255 символов, уходит вебхук invoice.status_changed как при реальной ошибке) и qr_scanned (только для QR-счетов: статус остаётся pending, уходит вебхук invoice.qr_scanned с qr_substate=scanned, повтор → 400 already_scanned). Симуляция работает ТОЛЬКО в песочнице (is_sandbox=true); в рабочем режиме недоступна ни при каких условиях (боевой счёт → 403 not_sandbox). Переход только из pending (иначе 400 invalid_status_transition). Отдельный лимит 60 запросов/мин на ключ. (2) Новые read-only эндпоинты GET /api/v1/webhook-logs и GET /api/v1/webhook-logs/{id} (X-API-Key) — программная верификация доставки вебхуков: фильтры invoice_id, event, status, date_from/date_to, плоская пагинация {current_page, data, total}; поля event, url, response_status, status, request_body, response_body, response_time_ms, created_at; чужой лог → 404. Retry в v1 нет (только в кабинете). Sandbox-вебхуки: 3 попытки, backoff 5с/15с (в проде до 11 попыток ~2ч), успех = любой 2xx. Изменения аддитивные и обратносовместимые.
• 2026-07-06 [new] POST /invoices: задокументирован ключ идемпотентности external_order_id_idempotency. Если передать external_order_id_idempotency (до 191 символа), повторный запрос с тем же значением не создаёт дубликат, а возвращает 409 с error `duplicate_idempotency_key` (в теле invoice_id и status существующего счёта). Перевыставить счёт с тем же external_order_id_idempotency можно только когда предыдущий счёт с этим ключом уже в статусе expired, cancelled или error. Это отдельное поле: external_order_id (до 255 символов) остаётся справочным внешним ID заказа (сохраняется в счёте, приходит в вебхуках, участвует в поиске) и ключом идемпотентности не является. Дополнительно в теле POST /invoices задокументирован опциональный kaspi_connection_id (ID кассира) — для организаций с несколькими активными кассами; при отсутствии выбранной primary-кассы и нескольких активных возвращается 422 connection_ambiguous (ранее это было описано только для QR-счетов POST /invoices/qr). Изменения документационные и аддитивные: поведение бэкенда не менялось.
• 2026-07-06 [new] В каталог error_code добавлены антифрод-коды защиты пользователей Kaspi от злоупотреблений (каталог расширен до 27 значений): trial_daily_limit (на пробном тарифе лимит 50 счетов/сутки), outstanding_recipient_limit и outstanding_org_limit (слишком много неоплаченных счетов на одного получателя / по организации), recipient_fanout_exceeded (превышен темп рассылки счетов по разным получателям, fan-out) — все четыре приходят синхронно как HTTP 429 с заголовком Retry-After; content_rejected — содержимое счёта отклонено проверкой, HTTP 422. Стройте обработку по error_code. Изменение документационное и аддитивное.
• 2026-07-01 [new] Добавлен новый эндпоинт POST /api/v1/catalog/scan — синхронный резолв штрихкода в Нацкаталоге Kaspi. Возвращает список товаров-кандидатов (id, name, ntin, gtin, barcode, unit_id, image_link) + normalized_barcode + scan_result; один штрихкод может дать несколько кандидатов (общий gtin, разные ntin). Пустой data[] означает, что товар не найден в Нацкаталоге — это НЕ ошибка (HTTP 200). Лимиты: 30 запросов/мин и 2000/сутки на API-ключ; circuit-breaker: при троттлинге Kaspi ~90 секунд сразу отдаётся 429. Ошибки сканирования: 400 kaspi_session_expired (нужна переавторизация кассира Kaspi), 429 kaspi_throttled (тело retry_after_seconds, заголовок Retry-After), 503 kaspi_scan_unavailable. Дополнительно при создании товара (POST /catalog) появились опциональные поля ntin, gtin и from_catalog, а при редактировании (PATCH /catalog/{id}) — опциональные ntin и gtin; в ответах GET и POST /catalog у товара добавилось поле gtin (может быть null). Все изменения аддитивные и обратносовместимые. ВАЖНО: при обычном редактировании (PATCH) НЕ передавайте ntin/gtin — пустое значение (null) затрёт идентичность Нацкаталога в Kaspi и его нельзя восстановить синхронизацией.
• 2026-06-24 [changed] Поэлементный возврат (POST /invoices/{id}/refund, return_items[]) теперь принимает на позицию РОВНО одно из двух полей: count (целые штуки, как раньше; сумма = price × count) ЛИБО amount (произвольная сумма по позиции, 0.01 … 9 999 999.99, не больше остатка по позиции). Это позволяет вернуть часть денег по неделимой позиции (count=1, например услуга). Указание обоих полей или ни одного — ошибка 422 (Validation failed) с ключами errors.return_items.{i} (оба/ни одного) и errors.return_items.{i}.amount|count (превышение остатка). Изменение аддитивное и обратносовместимое: старый формат с count работает без изменений. В ответе 201 и в вебхуке invoice.refunded у позиции, возвращённой по amount, refund.items[].count = 0, а деньги — в amount.
• 2026-06-15 [changed] Для QR-счетов (POST /invoices/qr) поле description ограничено 100 символами — это наименование позиции в QR-чеке Kaspi, длина которой ограничена самим Kaspi. При превышении возвращается 422 (Validation failed) с errors.description. На телефонные счета (POST /invoices) ограничение не распространяется — там description по-прежнему до 500 символов. Рекомендация для QR: краткое описание (номер заказа + имя), без длинных названий.
• 2026-06-14 [new] Новое вебхук-событие invoice.qr_scanned: клиент отсканировал QR-счёт и находится на экране оплаты Kaspi. status остаётся pending, payload содержит маркер qr_substate=scanned. Событие аддитивное, шлётся ровно один раз на QR-счёт и транзиентно — после него штатно приходит invoice.status_changed со status paid (оплатил) или cancelled (свернул/закрыл приложение). HMAC-подпись не менялась.
• 2026-06-14 [changed] Изменена модель жизненного цикла QR-счетов (POST /invoices/qr). QR-счета теперь СОСУЩЕСТВУЮТ: создание нового QR на той же кассе больше НЕ отменяет прежние — старый QR остаётся pending и мониторится до своего терминала, вебхук cancelled с текстом «Заменён новым QR-счётом #N» больше НЕ приходит. Два параллельных запроса оба получают 201 + pending (409 superseded остался как defensive-ветка, на практике недостижим). status cancelled по QR теперь означает реальную отмену клиентом (NotConfirmedByUser / CancelledByUser), а не системную замену. status expired по QR приходит только когда Kaspi отдал терминал (QrTokenDiscarded) — реагируйте на терминальные вебхуки по каждому invoice.id отдельно (возможны два paid), а не по локальному таймеру qr_expires_at. Жизненный цикл QR — минуты, не 24 часа (phone-счета по-прежнему 24 часа). Гарантия: по каждому QR в итоге придёт ровно один терминальный вебхук даже при рестарте воркера.
• 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 спецификация: добавлены новые поля в каталоге (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 документации с единым источником правды