kaspi-gateway

Единый платёжный API поверх Kaspi. У Kaspi нет публичного платёжного API и вебхуков — шлюз собирает подтверждение оплаты из доступных источников (выписка, чек клиента, Kaspi Магазин, ручная отметка) и отдаёт проектам один нормальный интерфейс со счетами и подписанными вебхуками.

Аутентификация

X-Api-Key: kg_live_...

Счёт

POST /v1/invoices
{"amount": 195000, "currency": "KZT",
 "customer": {"name":"Ислам Нуров","phone":"77015554433"},
 "reference": "pilgrim_42", "expires_in_hours": 168}

→ {"invoice": {"id":"inv_...", "code":"K7QD4M", "amount_exact":195000.01,
   "pay_url":"https://pay.kaspi.kz/pay/xxxx", "qr_url":".../qr.png",
   "payment_instruction":"Оплатите ... и укажите в комментарии код K7QD4M"}}

Код счёта уходит в комментарий платежа, а сумма получает уникальные тиыны — по любому из этих признаков платёж потом находится однозначно.

Подтверждение оплаты

POST /v1/statements   {"file":"<base64>","filename":"vypiska.pdf"}   # выписка из кабинета
POST /v1/receipts     {"image":"<base64>","phone":"77015554433"}      # чек от клиента
POST /v1/invoices/:id/pay  {"by":"Фархад"}                          # вручную
POST /v1/shop/sync                                                   # Kaspi Магазин (официальный API)

Вебхуки

invoice.created · invoice.paid · invoice.cancelled · invoice.expired
payment.review (совпадение неточное) · payment.unmatched · ping

Заголовки: X-Kaspi-Event, X-Kaspi-Timestamp, X-Kaspi-Signature: sha256=<hmac>
Проверка: hmac_sha256(secret, timestamp + "." + rawBody)

Статусы

счёт:   pending → paid | cancelled | expired
платёж: applied (проведён) | review (нужна проверка) | unmatched | rejected