API құжаттамасы
Kaspi арқылы төлем қабылдауға арналған REST API. Шот шығарасыз — клиентке Kaspi қосымшасында хабарлама келеді, ал төленген сәтте сізге webhook жетеді.
| Базалық мекенжай |
https://pay.qajet.online/api/v1 |
| Аутентификация |
X-API-Key: сіздің_кілтіңіз |
| Content-Type |
application/json |
Бастау
- Кассир қосыңыз — кабинетте, нөмір мен SMS коды арқылы.
- API кілтін алыңыз — Настройки бөлімінде бір батырма.
- Шот шығарыңыз — бір POST сұранысы, төменде.
Sandbox
— кабинеттен sandbox кілтін жасасаңыз, шоттар тестік деп белгіленеді де, нақты Kaspi-ге кетпейді.
Аутентификация
Әр сұраныста кілт тақырыпта жіберіледі. Кілт базада хештеліп сақталады — жоғалса, жаңасын жасау керек.
X-API-Key: qp_live_...
Кілтсіз немесе жарамсыз кілтпен API 401 қайтарады.
Қателер
Барлық қате бірдей пішінде келеді. Клиент коды тұрақты «error» өрісіне қарап тармақталуы керек — «message» адамға арналған және өзгеруі мүмкін.
{
"error": "invoice_not_found",
"message": "Счёт не найден"
}
| HTTP | error | Не істеу керек |
| 401 | unauthorized | Кілтті тексеріңіз |
| 402 | subscription_expired | Срок подписки истёк |
| 409 | idempotency_conflict | Қате емес — invoice_id алыңыз |
| 409 | cashier_session_expired | Kaspi байланысы үзілді |
| 422 | validation_error | fields өрісін қараңыз |
| 429 | rate_limited | Retry-After күтіңіз |
| 502 | kaspi_unavailable | Қайталауға болады |
4xx қатесін қайталаудың мәні жоқ — сұраныстың өзінде мәселе.
Что видит клиент
Текст description клиент видит в приложении Kaspi — перед оплатой понимает, за что платит.
{"phone_number": "+7 700 123 45 67",
"amount": 5000,
"description": "Кофе Латте ×2, Круассан ×3"}
Ограничение — 60 символов (в QR-счёте 100). Kaspi обрезает длинное, поэтому самое важное пишите в начале.
internal_comment — отдельное поле, видно только вам: в Kaspi не уходит, клиент его не видит.
Это не фискальный чек: позиции, количество и цена за единицу не разделяются. Просто свободный текст.
Төлемді қалай білеміз
Екі жол бар. Webhook — негізгісі: төлем түскен сәтте сізге сұраныс келеді. Поллинг — қосалқы: шоттың статусын өзіңіз сұрайсыз.
Webhook денесі HMAC-SHA256 қолтаңбасымен келеді. Қолтаңбаны тексермесеңіз, кез келген адам «төленді» деген хабар жібере алады.
X-Webhook-Signature: sha256=...
X-Webhook-Timestamp: 1714000000
Полный пример приёмника и код проверки подписи — в руководстве по интеграции.
Маркетплейс: несколько продавцов
Если на одной платформе работают несколько продавцов, у каждого свой счёт в Kaspi. Деньги приходят напрямую продавцу — ни через платформу, ни через Qajet Pay не проходят.
Подключить кассира продавца вы не можете: авторизация Kaspi отправляет SMS на его номер. Поэтому платформа готовит место и выдаёт ссылку, а подключение продавец завершает сам.
POST /api/v1/sellers
{"name": "Айгүл дүкені", "external_ref": "seller-42"}
→ {"id": 7, "status": "pending",
"invite_url": "https://pay.qajet.online/join/3-leyYYp…"}
Ссылку отправляете продавцу. Когда он подключится, придёт событие seller.connected — только после этого ему можно выставлять счета:
POST /api/v1/invoices
{"phone_number": "+7 700 123 45 67", "amount": 5000, "cashier_id": 7}
Каждый счёт получает от Kaspi свой номер операции, поэтому даже если у одного кассира несколько открытых счетов — пусть и на одинаковые суммы — точно известно, какой именно оплачен.
Отчёт: GET /api/v1/invoices?seller_ref=seller-42
Счета
GET
/api/v1/invoices
Шоттар тізімі
Сұрау параметрлері
page
|
int |
|
per_page
|
int |
|
status
|
string? |
|
kind
|
string? |
|
phone
|
string? |
|
external_order_id
|
string? |
|
cashier_id
|
int? |
Маркетплейсте — сатушы бойынша сүзу |
seller_ref
|
string? |
Сол сатушы, бірақ сіздің өз идентификаторыңыз бойынша |
search
|
string? |
Сипаттама/заметка ішінен |
created_from
|
string? |
|
created_to
|
string? |
|
POST
/api/v1/invoices
Телефон бойынша шот
Клиентке Kaspi қосымшасында push келеді. Шот 24 сағат күтеді.
Дене
amount
міндетті
|
number |
|
phone_number
міндетті
|
string |
Кез келген пішінде: `87001234567`, `+7 700 123 45 67`, `7001234567`. Сервер оны Kaspi күтетін түрге келтіреді. |
cashier_id
|
int? |
Бірнеше кассир болса — қайсысы. Әдепкі: негізгі. |
description
|
string? |
Клиент Kaspi-де көретін мәтін. Kaspi алғашқы ~60 таңбасын ғана көрсетеді, сондықтан ең маңыздысын басына жазыңыз. |
external_order_id
|
string? |
|
idempotency_key
|
string? |
Қайталанған сұраныс дубль шот жасамауы үшін. Сол кілтпен қайта жіберсеңіз — 409. Бұрынғысы сәтсіз бітсе, жаңасы жасалады. |
internal_comment
|
string? |
Тек сіз үшін — Kaspi-ге жіберілмейді, клиент көрмейді. |
POST
/api/v1/invoices/check-client
Нөмірді Kaspi-де тексеру
Шот шығармас бұрын нөмірдің Kaspi-де бар-жоғын білуге болады.
Сұрау параметрлері
phone
міндетті
|
string |
Кез келген пішінде |
POST
/api/v1/invoices/qr
QR-шот
QR токенін қайтарады. Сканерлеу терезесі — бірнеше минут.
Дене
amount
міндетті
|
number |
|
cashier_id
|
int? |
|
description
|
string? |
|
external_order_id
|
string? |
|
idempotency_key
|
string? |
|
internal_comment
|
string? |
|
GET
/api/v1/invoices/stats
Статистика
Сұрау параметрлері
created_from
|
string? |
|
created_to
|
string? |
|
cashier_id
|
int? |
|
seller_ref
|
string? |
|
GET
/api/v1/invoices/{invoice_id}
Шотты алу
Webhook орнатпасаңыз, статусты осы арқылы сұрауға болады.
Жолдағы параметрлер
PATCH
/api/v1/invoices/{invoice_id}
Ішкі заметканы өзгерту
Тек ішкі заметка өзгереді — қалғаны Kaspi-де бекітілген.
Жолдағы параметрлер
Дене
POST
/api/v1/invoices/{invoice_id}/cancel
Шотты болдырмау
Жолдағы параметрлер
GET
/api/v1/invoices/{invoice_id}/qr.png
QR суреті
Жолдағы параметрлер
POST
/api/v1/invoices/{invoice_id}/refund
Қайтару жасау
Жолдағы параметрлер
Дене
amount
|
number? |
Берілмесе — қалдықтың барлығы қайтарылады. |
idempotency_key
|
string? |
|
reason
|
string? |
|
GET
/api/v1/invoices/{invoice_id}/refunds
Шот қайтарулары
Жолдағы параметрлер
POST
/api/v1/invoices/{invoice_id}/simulate
Төлемді имитациялау (тек sandbox)
Шотты қалаған күйге көшіреді — интеграцияны Kaspi-сіз тексеру үшін.
Тек `KASPI_DRIVER=mock` режимінде жұмыс істейді. Нақты Kaspi-мен бұл
эндпоинт әдейі жабық: өндірісте төлем күйін қолмен өзгерту — есепті
бұзудың ең қысқа жолы.
Жолдағы параметрлер
Сұрау параметрлері
state
міндетті
|
"paid" | "cancelled" | "expired" | "error" |
|
Постоянный QR
GET
/api/v1/static-qr
Тұрақты QR тізімі
Сұрау параметрлері
page
|
int |
|
per_page
|
int |
|
status
|
string? |
|
POST
/api/v1/static-qr
Тұрақты QR жасау
Қағазға басуға жарайтын сілтеме.
Kaspi-ге дәл қазір сұраныс кетпейді: нақты QR төлеуші сілтемені ашқанда
жасалады, сондықтан басылған сурет ешқашан ескірмейді.
Дене
amount
|
number? |
Берілмесе — төлеуші соманы өзі енгізеді. |
cashier_id
|
int? |
|
description
|
string? |
|
expires_at
|
string? |
|
external_order_id
|
string? |
|
idempotency_key
|
string? |
|
internal_comment
|
string? |
|
single_use
|
bool |
Бір рет төленгеннен кейін сілтеме жабылады. |
GET
/api/v1/static-qr/{code_id}
Тұрақты QR-ды алу
Жолдағы параметрлер
DELETE
/api/v1/static-qr/{code_id}
Тұрақты QR-ды өшіру
Жолдағы параметрлер
GET
/api/v1/static-qr/{code_id}/print.svg
Басып шығаруға арналған SVG
Векторлық нұсқа — қандай өлшемде басылса да анық қалады.
Жолдағы параметрлер
Возвраты
GET
/api/v1/refunds
Барлық қайтару
Сұрау параметрлері
page
|
int |
|
per_page
|
int |
|
status
|
string? |
|
Подписки
GET
/api/v1/subscriptions
Жазылымдар тізімі
Сұрау параметрлері
page
|
int |
|
per_page
|
int |
|
status
|
string? |
|
phone
|
string? |
|
POST
/api/v1/subscriptions
Жазылым құру
Қайталанатын шот құрады.
`starts_at` берілмесе, бірінші шот бірден шығады (фондық жұмысшы
бес минут ішінде іске қосады).
Дене
amount
міндетті
|
number |
|
interval_months
міндетті
|
int |
Шоттар арасындағы айлар саны: 1 — ай сайын, 3 — тоқсан сайын, 12 — жыл сайын. |
name
міндетті
|
string |
|
phone
міндетті
|
string |
|
cashier_id
|
int? |
|
description
|
string? |
|
ends_at
|
string? |
|
external_order_id
|
string? |
|
max_cycles
|
int? |
|
starts_at
|
string? |
Берілмесе — бірінші шот бірден шығады. |
GET
/api/v1/subscriptions/{subscription_id}
Жазылымды алу
Жолдағы параметрлер
subscription_id
міндетті
|
int |
|
PATCH
/api/v1/subscriptions/{subscription_id}
Жазылымды өзгерту
Нөмір мен аралық өзгертілмейді — олар жазылымның мәнін құрайды.
Жолдағы параметрлер
subscription_id
міндетті
|
int |
|
Дене
amount
|
number? |
|
description
|
string? |
|
ends_at
|
string? |
|
external_order_id
|
string? |
|
max_cycles
|
int? |
|
name
|
string? |
|
POST
/api/v1/subscriptions/{subscription_id}/cancel
Болдырмау
Қайтымсыз: болдырылған жазылымды қайта қосу мүмкін емес.
Жолдағы параметрлер
subscription_id
міндетті
|
int |
|
GET
/api/v1/subscriptions/{subscription_id}/invoices
Жазылым шоттары
Жолдағы параметрлер
subscription_id
міндетті
|
int |
|
Сұрау параметрлері
POST
/api/v1/subscriptions/{subscription_id}/pause
Тоқтату
Жолдағы параметрлер
subscription_id
міндетті
|
int |
|
POST
/api/v1/subscriptions/{subscription_id}/resume
Жалғастыру
Тоқтап тұрған кезде өтіп кеткен циклдар қуылмайды.
Әйтпесе клиент бірден бірнеше шот алар еді.
Жолдағы параметрлер
subscription_id
міндетті
|
int |
|
POST
/api/v1/subscriptions/{subscription_id}/run
Шотты дәл қазір шығару
Кезекті шотты күтпей шығарады.
Циклдің есебі жылжиды, келесі мерзім осы сәттен саналады — сондықтан
бұл «қосымша шот» емес, «мерзімінен бұрын».
Жолдағы параметрлер
subscription_id
міндетті
|
int |
|
Webhook-тар
GET
/api/v1/webhooks
Webhook тізімі
POST
/api/v1/webhooks
Webhook қосу
Құпия кілт **тек осы жауапта** көрсетіледі — сақтап қойыңыз.
Дене
url
міндетті
|
string |
|
description
|
string? |
|
events
|
string[] |
Бос тізім — барлық оқиға. |
GET
/api/v1/webhooks/deliveries
Жеткізу логтары
Сұрау параметрлері
page
|
int |
|
per_page
|
int |
|
status
|
string? |
|
event
|
string? |
|
POST
/api/v1/webhooks/deliveries/{delivery_id}/retry
Жеткізуді қайталау
Жолдағы параметрлер
DELETE
/api/v1/webhooks/{webhook_id}
Webhook өшіру
Жолдағы параметрлер
POST
/api/v1/webhooks/{webhook_id}/test
Тексеру хабары
Баптау дұрыс па — бірден көру үшін `ping` жібереді.
Жолдағы параметрлер
Кассиры
GET
/api/v1/cashiers
Кассирлер тізімі
POST
/api/v1/cashiers
Кассир қосу
Жазбасын жасайды; Kaspi авторизациясы бөлек қадамдармен жүреді.
Нөмірі белгілі болса, `connect_or_reuse` арқылы бар кассирді қайта
қолданған дұрыс — сонда дубль пайда болмайды.
Дене
label
|
string? |
Берілмесе «Касса N» деп автоматты қойылады. |
DELETE
/api/v1/cashiers/{cashier_id}
Кассирді өшіру
Кассирді жояды. Kaspi-дегі қызметкер жазбасына тиіспейді.
Шоты жоқ кассир толық өшіріледі. Шоты бары өшірілмейді — есептегі
байланыс сақталуы керек; оның орнына сессиясы жойылып, нөмірі
босатылады, сондықтан сол нөмірді кейін қайта қосуға болады.
Жолдағы параметрлер
POST
/api/v1/cashiers/{cashier_id}/auth/otp
3-қадам: SMS кодын растау
Қайтымсыз қадам: сәтті болса құрылғы Kaspi-де тіркеледі.
Жолдағы параметрлер
Дене
POST
/api/v1/cashiers/{cashier_id}/auth/phone
2-қадам: нөмірді жіберу (SMS)
Kaspi осы нөмірге SMS жібереді.
Жолдағы параметрлер
Дене
POST
/api/v1/cashiers/{cashier_id}/auth/start
1-қадам: авторизацияны бастау
Жолдағы параметрлер
GET
/api/v1/cashiers/{cashier_id}/health
Сессияны тексеру
Жолдағы параметрлер
POST
/api/v1/cashiers/{cashier_id}/primary
Негізгі ету
Жолдағы параметрлер
Системная
GET
/api/v1/status
Health-check
Авторизациясыз қолжетімді — мониторингке арналған.
Продавцы (маркетплейс)
GET
/api/v1/sellers
Сатушылар тізімі
Сұрау параметрлері
POST
/api/v1/sellers
Сатушыны шақыру
Орын дайындап, шақыру сілтемесін қайтарады.
Сілтемені сатушыға өзіңіз жеткізесіз. Ол ашып, өз нөмірін енгізеді,
SMS кодын растайды — содан кейін ғана оған шот шығаруға болады.
Дене
external_ref
|
string? |
Сіздің жүйеңіздегі сатушы идентификаторы. Тіркелгі ішінде қайталанбауы керек. Бұны берсеңіз, біздің `id`-мен өз нөміріңізді сәйкестендіріп отырудың қажеті болмайды. |
name
|
string? |
Сатушының атауы. Берілмесе «Касса N» деп қойылады. |
GET
/api/v1/sellers/{seller_id}
Сатушыны алу
Жолдағы параметрлер
POST
/api/v1/sellers/{seller_id}/reinvite
Жаңа шақыру сілтемесі
Ескі сілтеме сол сәтте жарамсыз болады.
Жолдағы параметрлер