Qajet Pay / Документация
RU
Swagger Кабинет

API құжаттамасы

Kaspi арқылы төлем қабылдауға арналған REST API. Шот шығарасыз — клиентке Kaspi қосымшасында хабарлама келеді, ал төленген сәтте сізге webhook жетеді.

Базалық мекенжай https://pay.qajet.online/api/v1
Аутентификация X-API-Key: сіздің_кілтіңіз
Content-Type application/json

Бастау

  1. Кассир қосыңыз — кабинетте, нөмір мен SMS коды арқылы.
  2. API кілтін алыңыз — Настройки бөлімінде бір батырма.
  3. Шот шығарыңыз — бір POST сұранысы, төменде.
Sandbox — кабинеттен sandbox кілтін жасасаңыз, шоттар тестік деп белгіленеді де, нақты Kaspi-ге кетпейді.

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

Әр сұраныста кілт тақырыпта жіберіледі. Кілт базада хештеліп сақталады — жоғалса, жаңасын жасау керек.

X-API-Key: qp_live_...

Кілтсіз немесе жарамсыз кілтпен API 401 қайтарады.

Қателер

Барлық қате бірдей пішінде келеді. Клиент коды тұрақты «error» өрісіне қарап тармақталуы керек — «message» адамға арналған және өзгеруі мүмкін.

{
  "error": "invoice_not_found",
  "message": "Счёт не найден"
}
HTTPerrorНе істеу керек
401unauthorizedКілтті тексеріңіз
402subscription_expiredСрок подписки истёк
409idempotency_conflictҚате емес — invoice_id алыңыз
409cashier_session_expiredKaspi байланысы үзілді
422validation_errorfields өрісін қараңыз
429rate_limitedRetry-After күтіңіз
502kaspi_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 орнатпасаңыз, статусты осы арқылы сұрауға болады.

Жолдағы параметрлер

invoice_id міндетті int
PATCH /api/v1/invoices/{invoice_id}

Ішкі заметканы өзгерту

Тек ішкі заметка өзгереді — қалғаны Kaspi-де бекітілген.

Жолдағы параметрлер

invoice_id міндетті int

Дене

internal_comment string?
POST /api/v1/invoices/{invoice_id}/cancel

Шотты болдырмау

Жолдағы параметрлер

invoice_id міндетті int
GET /api/v1/invoices/{invoice_id}/qr.png

QR суреті

Жолдағы параметрлер

invoice_id міндетті int
POST /api/v1/invoices/{invoice_id}/refund

Қайтару жасау

Жолдағы параметрлер

invoice_id міндетті int

Дене

amount number? Берілмесе — қалдықтың барлығы қайтарылады.
idempotency_key string?
reason string?
GET /api/v1/invoices/{invoice_id}/refunds

Шот қайтарулары

Жолдағы параметрлер

invoice_id міндетті int
POST /api/v1/invoices/{invoice_id}/simulate

Төлемді имитациялау (тек sandbox)

Шотты қалаған күйге көшіреді — интеграцияны Kaspi-сіз тексеру үшін. Тек `KASPI_DRIVER=mock` режимінде жұмыс істейді. Нақты Kaspi-мен бұл эндпоинт әдейі жабық: өндірісте төлем күйін қолмен өзгерту — есепті бұзудың ең қысқа жолы.

Жолдағы параметрлер

invoice_id міндетті int

Сұрау параметрлері

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-ды алу

Жолдағы параметрлер

code_id міндетті int
DELETE /api/v1/static-qr/{code_id}

Тұрақты QR-ды өшіру

Жолдағы параметрлер

code_id міндетті int
GET /api/v1/static-qr/{code_id}/print.svg

Басып шығаруға арналған SVG

Векторлық нұсқа — қандай өлшемде басылса да анық қалады.

Жолдағы параметрлер

code_id міндетті int

Возвраты

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

Сұрау параметрлері

page int
per_page 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

Жеткізуді қайталау

Жолдағы параметрлер

delivery_id міндетті int
DELETE /api/v1/webhooks/{webhook_id}

Webhook өшіру

Жолдағы параметрлер

webhook_id міндетті int
POST /api/v1/webhooks/{webhook_id}/test

Тексеру хабары

Баптау дұрыс па — бірден көру үшін `ping` жібереді.

Жолдағы параметрлер

webhook_id міндетті int

Кассиры

GET /api/v1/cashiers

Кассирлер тізімі

POST /api/v1/cashiers

Кассир қосу

Жазбасын жасайды; Kaspi авторизациясы бөлек қадамдармен жүреді. Нөмірі белгілі болса, `connect_or_reuse` арқылы бар кассирді қайта қолданған дұрыс — сонда дубль пайда болмайды.

Дене

label string? Берілмесе «Касса N» деп автоматты қойылады.
DELETE /api/v1/cashiers/{cashier_id}

Кассирді өшіру

Кассирді жояды. Kaspi-дегі қызметкер жазбасына тиіспейді. Шоты жоқ кассир толық өшіріледі. Шоты бары өшірілмейді — есептегі байланыс сақталуы керек; оның орнына сессиясы жойылып, нөмірі босатылады, сондықтан сол нөмірді кейін қайта қосуға болады.

Жолдағы параметрлер

cashier_id міндетті int
POST /api/v1/cashiers/{cashier_id}/auth/otp

3-қадам: SMS кодын растау

Қайтымсыз қадам: сәтті болса құрылғы Kaspi-де тіркеледі.

Жолдағы параметрлер

cashier_id міндетті int

Дене

otp міндетті string
POST /api/v1/cashiers/{cashier_id}/auth/phone

2-қадам: нөмірді жіберу (SMS)

Kaspi осы нөмірге SMS жібереді.

Жолдағы параметрлер

cashier_id міндетті int

Дене

phone міндетті string
POST /api/v1/cashiers/{cashier_id}/auth/start

1-қадам: авторизацияны бастау

Жолдағы параметрлер

cashier_id міндетті int
GET /api/v1/cashiers/{cashier_id}/health

Сессияны тексеру

Жолдағы параметрлер

cashier_id міндетті int
POST /api/v1/cashiers/{cashier_id}/primary

Негізгі ету

Жолдағы параметрлер

cashier_id міндетті int

Системная

GET /api/v1/status

Health-check

Авторизациясыз қолжетімді — мониторингке арналған.

Продавцы (маркетплейс)

GET /api/v1/sellers

Сатушылар тізімі

Сұрау параметрлері

status string?
POST /api/v1/sellers

Сатушыны шақыру

Орын дайындап, шақыру сілтемесін қайтарады. Сілтемені сатушыға өзіңіз жеткізесіз. Ол ашып, өз нөмірін енгізеді, SMS кодын растайды — содан кейін ғана оған шот шығаруға болады.

Дене

external_ref string? Сіздің жүйеңіздегі сатушы идентификаторы. Тіркелгі ішінде қайталанбауы керек. Бұны берсеңіз, біздің `id`-мен өз нөміріңізді сәйкестендіріп отырудың қажеті болмайды.
name string? Сатушының атауы. Берілмесе «Касса N» деп қойылады.
GET /api/v1/sellers/{seller_id}

Сатушыны алу

Жолдағы параметрлер

seller_id міндетті int
POST /api/v1/sellers/{seller_id}/reinvite

Жаңа шақыру сілтемесі

Ескі сілтеме сол сәтте жарамсыз болады.

Жолдағы параметрлер

seller_id міндетті int

Qajet Pay — тәуелсіз жоба, Kaspi Bank-пен байланысты емес.