Действующая редакция контракта. Обновлено: 2026-11-16.
Для ИИ-ассистентов и no-code инструментов
Машиночитаемая версия этой страницы: kazpayment.kz/docs/api.md (она же /llms.txt). Готовый промпт для ChatGPT, Claude или Cursor — ещё несколько на странице промптов:
Прочитай документацию https://kazpayment.kz/docs/api.md и подключи приём оплаты KazPayment в мой проект: создание заказа (POST /api/v1/orders с идемпотентным external_ref), переход покупателя по pay_url, обработчик вебхука об оплате с проверкой подписи X-Kazpayment-Signature ДО разбора JSON. Ключ интеграции и секрет вебхука вынеси в переменные окружения — значения я подставлю сам.
API для интеграции — /api/v1
Для чужой системы: интернет-магазина, телеграм-бота, службы доставки. Всё, что ей нужно, — завести заказ и узнать, оплачен ли он.
Действующая редакция всегда открыта на kazpayment.kz/docs/api — страница собирается из этого файла при каждой выкладке.
Порог документа: по нему должен подключиться человек, не читавший наш код. Если при чтении пришлось лезть в исходники — это дефект документа, а не читателя.
Быстрый старт за пять минут
Четыре запроса от ключа до подтверждённой оплаты. Подставьте свой ключ в
KEY и выполняйте по порядку.
API и вебхуки работают на любом тарифе, включая Free. На Free через API
можно создать до 500 заказов за 30 дней, а подписок — пока за эти 30 дней
их заведено меньше 500 (считая заведённые в кабинете); дальше
новый заказ получает 403 free_order_limit, новая подписка —
403 free_subscription_limit (повтор уже заведённого — нет).
В песочнице предела нет.
KEY="ваш_ключ_интеграции"
API="https://kazpayment.kz/api/v1"
# 1. Ключ рабочий?
curl -s "$API/whoami" -H "Authorization: Bearer $KEY"
# → {"tenantId":"…","role":"integration"}
# 2. Завести заказ. external_ref — ВАШ номер заказа.
curl -s -X POST "$API/orders" \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"external_ref":"TEST-1","amount":100,"comment":"Проверка"}'
# → {"orderRef":"TEST-1","status":"pending","payUrl":"https://kazpayment.kz/pay/…"}
# 3. Открыть payUrl в браузере и оплатить (в песочнице — кнопка
# «Оплатить» в жёлтом блоке на той же странице).
# 4. Проверить статус.
curl -s "$API/orders/TEST-1" -H "Authorization: Bearer $KEY"
# → {"orderRef":"TEST-1","status":"paid","paidAmount":100,…}
Работает — переходите к вебхуку, чтобы не опрашивать статус вручную. Пошаговое руководство с проверками на каждом шаге: Подключить интернет-магазин или телеграм-бот.
Готовые SDK: Node.js, Python, PHP
Обёртка над этим API на трёх языках — без зависимостей, по одному-два файла.
Ключ, коды ошибок, повтор при 429 rate_limited и проверка подписи вебхука
уже внутри. Повторяет запрос при обрыве сети SDK только там, где это
безопасно: заказ (по external_ref), возврат (по refund_ref), отмена заказа,
код с idempotency_key, смена настроек, чтение. SMS, сообщения и счёт в
Kaspi на номер при обрыве не повторяются — иначе покупатель получил бы два;
клиента и подписку тоже не повторяют — при обрыве сперва посмотрите список
подписок. Ответ 200 не в JSON (прокси, страница
защиты) — ошибка bad_response, а не «успех без полей».
| Язык | Файлы | Требования |
|---|---|---|
| Node.js | kazpayment.js, kazpayment.d.ts | Node.js 18+ |
| Python | kazpayment.py | Python 3.8+, только стандартная библиотека |
| PHP | Client.php, KazPaymentException.php | PHP 7.4+, ext-curl |
import { KazPayment, parseWebhook } from './kazpayment.js';
const kp = new KazPayment({ apiKey: process.env.KAZPAYMENT_KEY });
const order = await kp.createOrder({ externalRef: 'YESH-1201', amount: 4500, customerPhone: '+77771234567' });
// order.payUrl — отправьте покупателя сюда
// В приёмнике вебхука — по СЫРОМУ телу запроса:
const event = parseWebhook(rawBody, req.headers['x-kazpayment-signature'], process.env.KAZPAYMENT_WEBHOOK_SECRET);
if (event.event === 'payment.received') { /* заказ event.order_ref оплачен */ }
import os
from kazpayment import KazPayment, parse_webhook
kp = KazPayment(os.environ["KAZPAYMENT_KEY"])
order = kp.create_order("YESH-1201", 4500, customer_phone="+77771234567")
event = parse_webhook(raw_body, headers.get("X-Kazpayment-Signature"), os.environ["KAZPAYMENT_WEBHOOK_SECRET"])
require 'KazPaymentException.php';
require 'Client.php';
$kp = new KazPayment\Client(getenv('KAZPAYMENT_KEY'));
$order = $kp->createOrder('YESH-1201', 4500, null, '+77771234567');
$event = KazPayment\Client::parseWebhook(file_get_contents('php://input'), $_SERVER['HTTP_X_KAZPAYMENT_SIGNATURE'] ?? null, getenv('KAZPAYMENT_WEBHOOK_SECRET'));
Ошибка API — исключение KazPaymentError (PHP: KazPayment\KazPaymentException)
с HTTP-статусом и машинным кодом из таблицы Ошибки.
Что умеет SDK (имена — Node.js и PHP; в Python то же змеиным регистром,
create_order, set_unpaid_policy…):
| Раздел | Методы |
|---|---|
| Заказы | createOrder, getOrder, cancelOrder, refundOrder, sendInvoice (счёт в Kaspi на номер), notifyOrder |
| Абонементы | listPlans, createPayer, createSubscription, listSubscriptions, setSubscriptionStatus |
| Настройки бизнеса | getUnpaidPolicy, setUnpaidPolicy, getPlanUnpaidPolicy, setPlanUnpaidPolicy, getAutoBilling, startAutoBilling |
| Сообщения и коды | sendSms, whatsappOrder, whatsappCart, requestOtp, verifyOtp |
| Показатели | getMetrics, setMetricsDigest |
| Вебхук | setWebhook, getWebhook, deleteWebhook, testWebhook, parseWebhook, verifyWebhookSignature |
| Прочее | whoami, kaspiStatus, request — любой метод API, которого ещё нет в SDK |
Что тут есть и чего нет
Есть: заказ, ссылка на его оплату, отправка этой ссылки покупателю в WhatsApp, статус, вебхук об оплате, подтверждение телефона кодом из SMS, абонементы (клиент + подписка на тариф).
Свободных сообщений в WhatsApp нет. Вне суток с последнего сообщения человека WhatsApp принимает только заранее одобренные Meta шаблоны — это её правило, не наше. Поэтому API умеет отправить ссылку на оплату по нашему шаблону, но не «любой текст любому номеру».
Отмена и возврат в API есть. Отменить ещё не оплаченный заказ — POST /api/v1/orders/{номер}/cancel; вернуть деньги по оплаченному — POST /api/v1/orders/{номер}/refund.
Ключ
Выпускается в кабинете: «Подключения» → «Интеграция» → «Выпустить ключ». Там же настраивается вебхук и виден список живых ключей — по последним четырём символам, чтобы отозвать нужный, а не все подряд.
Ключ и вебхук доступны на любом тарифе, включая Free.
Открытое значение показывается один раз — в базе лежит только его хеш, восстановить нельзя. Потеряли — выпустите новый, а старый отзовите.
Выпустить и отозвать может владелец бизнеса, но не сотрудник: ключ открывает заказы и возвраты, то есть деньги.
Передаётся как Authorization: Bearer <ключ>.
Ключ работает только в /api/v1/. В кабинет он не ходит: ни на чтение, ни
на запись. Это сделано ради вас же — утечка ключа из магазина не открывает
список ваших клиентов.
Отзыв — поштучный, в том же разделе кабинета. Прежний общий отзыв гасил все ключи бизнеса разом, включая работающие интеграции.
Проверка ключа
GET /api/v1/whoami
→ 200 {"tenantId": "a9a9196a-…", "role": "integration"}
Первое, что стоит вызвать после получения ключа. Если тут 401 — дело в ключе, и
дальше можно не искать. Текст ответа подскажет, в чём именно: «Требуется токен
доступа» — ключ не дошёл (нет заголовка Authorization: Bearer <ключ>),
«Ключ не принят» — ключ дошёл, но неверный, отозван или устарел; тогда
выпустите новый в кабинете: «Подключения» → «Интеграция» → «Выпустить ключ».
Завести заказ
POST /api/v1/orders
Content-Type: application/json
{
"external_ref": "YESH-1201",
"amount": 4500,
"comment": "Пицца Маргарита",
"customer_phone": "+7 777 123 45 67"
}
| поле | обяз. | что это |
|---|---|---|
external_ref |
да | номер заказа В ВАШЕЙ системе, до 128 символов; в пути статуса передаётся URL-кодированным |
amount |
да | целое число тенге, больше нуля |
comment |
нет | что оплачивают, до 200 символов; видит оператор бизнеса, и он же попадает в счёт Kaspi (см. Текст счёта в Kaspi) |
customer_phone |
нет | телефон покупателя в любом виде — +7…, 8…, 777… |
invoice_text |
нет | текст счёта в приложении Kaspi ровно как есть, до 200 символов — см. ниже |
Ответ:
{
"orderRef": "YESH-1201",
"amount": 4500,
"paidAmount": 0,
"status": "pending",
"created": true,
"invoiceText": "Заказ Пицца Маргарита · YESH-1201",
"payUrl": "https://kazpayment.kz/pay/7f3a…"
}
201 — заказ заведён, 200 — найден по номеру (см. ниже).
Текст счёта в Kaspi
Покупатель с customer_phone получает счёт в приложении Kaspi с подписью. Без
invoice_text она собирается так: Заказ <comment> · <external_ref> (из
comment — первые 40 символов), без comment — Заказ <external_ref>.
Нужен свой текст — передайте invoice_text: покупатель увидит ровно его, без
«Заказ», без номера и без смены регистра. Переносы строк и повторные пробелы
сводятся к одному пробелу. external_ref при этом никуда не девается: по нему
работают повторы, GET /orders/{номер}, вебхуки и сверка.
{
"external_ref": "planfix-aray-241335-10",
"amount": 25000,
"customer_phone": "+7 777 123 45 67",
"invoice_text": "Оплата брони гостевого дома Арай"
}
Что именно увидит покупатель, приходит в ответе полем invoiceText — и при
создании, и в статусе заказа. В
песочнице тоже: текст проверяется без
настоящего счёта. Заданный invoice_text стоит и на странице payUrl как
назначение платежа.
Как и comment, invoice_text при повторе с тем же номером игнорируется:
текст счёта уже выставленного заказа не меняется.
Повтор безопасен
Запрос идемпотентен по external_ref: повторный вызов с тем же номером не
заводит второй заказ и не требует денег дважды. Вместо этого возвращается
существующий заказ, created: false — и свежая ссылка на оплату.
Поэтому правильная реакция на таймаут — просто повторить запрос с тем же телом.
Повтор с другой суммой — ошибка, а не обновление: придёт 422 с кодом
order_amount_differs. Изменить сумму существующего заказа нельзя — покупатель
изменил корзину, значит заведите заказ с новым номером. Комментарий при
повторе игнорируется.
Обратная сторона: номер должен быть уникален в вашей системе. Если вы переиспользуете номера, второй заказ с тем же номером не заведётся.
Зачем customer_phone
Передали — покупатель заводится клиентом бизнеса (раздел «Клиенты» в кабинете), и ему можно слать напоминания об оплате. Не передали — заказ анонимный: платить по нему можно, но напоминать некому.
Для доставки телефон обычно и так известен, так что передавать его стоит.
Ссылка на оплату
payUrl — адрес страницы, на которой покупатель нажимает «Оплатить» и получает
QR-код. Код действует три минуты (столько даёт Kaspi), поэтому выпускается
он не при открытии страницы, а по нажатию; когда истечёт, на странице есть
кнопка «Выпустить заново».
Платить можно из любого банковского приложения, не только Kaspi: это Единый QR. Проверено живой оплатой из Halyk.
Открытая на телефоне, страница первой предлагает «Оплатить в Kaspi»: одно
нажатие открывает приложение Kaspi с суммой заказа. Номер покупателя для этого
не нужен — ведите его на payUrl, и всё. Бизнес может выключить эту кнопку
(«Бизнес» → «Настройки» → «Страница оплаты» → «Как на компьютере»): тогда и на телефоне
страница показывает QR и счёт на номер. Ссылка и ответы API от этого не
меняются.
Страницу можно встроить в свой сайт через iframe — она это разрешает. Остальные наши страницы встраивать нельзя.
Ссылка живёт, пока заказ не оплачен. Нужна новая — повторите создание заказа тем же номером.
Оплата одним нажатием с вашей страницы
Чтобы покупатель с телефона попадал сразу в приложение Kaspi, без нашей
страницы со второй кнопкой, отправьте форму методом POST на
/api/public/pay/{токен}/go, где токен — последняя часть payUrl:
<form method="post" action="https://kazpayment.kz/api/public/pay/7f3a…/go">
<button type="submit">Оплатить в Kaspi</button>
</form>
На телефоне мы выпускаем код и сразу открываем Kaspi с суммой заказа. С компьютера, у бизнеса с настройкой «как на компьютере» и в песочнице — открывается обычная страница оплаты с QR. Форма, а не ссылка: ссылку открывают роботы предпросмотра в мессенджерах, а iPhone открывает Kaspi только по переходу, начатому нажатием человека.
Счёт в приложение Kaspi на номер
С компьютера QR неудобен. Если номер покупателя вам известен (он вошёл по коду из SMS), выставьте счёт прямо в его приложение Kaspi:
POST /api/v1/orders/{номер}/remote
{"phone": "+7 701 999 88 77"}
→ 200 {"orderRef": "YESH-1201", "sent": true}
Покупатель увидит счёт в приложении Kaspi через несколько секунд. Если по заказу был выпущен QR, он гасится — живой остаётся один счёт.
| HTTP | code |
что значит |
|---|---|---|
| 422 | invoice_rejected |
Kaspi не принял счёт на этот номер. Чаще всего на номере нет Kaspi — предложите оплату по QR или другой номер |
| 422 | invoice_already_paid |
прежний счёт по заказу уже оплачен, новый не ушёл: не предлагайте платить снова. Обычно оплата придёт через минуты; если заказ остался неоплаченным, решать будет бизнес |
| 404 | order_not_found |
заказа с таким номером нет |
| 400 | invalid_request |
номер не похож на казахстанский, заказ закрыт, или живой QR ещё действует (подождите минуту) |
Номер, указанный при создании заказа в customer_phone, по умолчанию получает
счёт сам примерно через минуту. Если Kaspi его не принял (например, на номере
нет Kaspi), в ответе GET /api/v1/orders/{номер} появится поле
invoiceError с причиной — предложите покупателю другой способ.
Если прежний счёт исчез из Kaspi без оплаты и новый ждёт паузу
(reissue_pause_days), там же будет поле nextInvoiceAt — когда он уйдёт.
Отменить заказ
Покупатель передумал, товара нет, заказ заведён по ошибке — отмените его, и платить по нему станет нельзя: счёт в приложении Kaspi гасится, страница оплаты отвечает «платить нечего».
curl -s -X POST "$API/orders/YESH-1201/cancel" \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"reason":"покупатель передумал"}'
# → {"orderRef":"YESH-1201","status":"cancelled","repeated":false,"paidAmount":0,"invoiceClosed":true}
reason необязателен: он попадает в журнал заказа в кабинете бизнеса, до
покупателя не доходит.
Повтор безопасен
Повторный запрос по уже отменённому заказу отвечает 200 с "repeated": true
— денег и счетов он не трогает. После таймаута повторяйте смело.
Ответы
| HTTP | code |
что значит |
|---|---|---|
| 200 | — | отменён (или был отменён раньше — repeated: true) |
| 404 | order_not_found |
заказа с таким номером нет |
| 409 | order_already_paid |
заказ оплачен — отменять нечего, нужен возврат. Сюда же — оплата, пришедшая в ту же секунду, что отмена |
| 409 | order_partially_paid |
часть денег уже пришла, и бизнес выбрал в таких случаях отказывать (см. ниже). В ответе paidAmount |
409 повторять бесполезно: ответ не изменится.
Частично оплаченный заказ
Что делать, если часть денег уже пришла, решает бизнес в кабинете: «Подключения» → «Интеграция» → «Отмена частично оплаченного заказа».
- Отказать (по умолчанию) — заказ не отменяется, ответ
409 order_partially_paid. Сначала верните полученное, затем отмените. - Отменить остаток — счёт на оставшуюся сумму гасится, полученное остаётся
у бизнеса; ответ
200, вpaidAmount— сколько получено.
Что нельзя забрать назад: QR-код
Если покупатель уже открыл страницу оплаты и получил QR-код, Kaspi не даёт
отменить этот код — он живёт свои три минуты. Заплатить по нему после отмены
можно, и такие деньги мы не прячем: заказ становится paid, а вебхук
payment.received приходит с "late": true. Решите у себя, что с ним делать:
выдать заказ или вернуть деньги.
invoiceClosed: false
Касса бизнеса не ответила в момент отмены. Заказ всё равно отменён — новых
счетов по нему не будет, — а уже выставленный счёт в приложении Kaspi мы
погасим сами в ближайшие минуты. Делать ничего не нужно; если за эти минуты
покупатель успеет его оплатить — см. абзац выше про late.
Вернуть деньги покупателю
POST /api/v1/orders/YESH-1201/refund
{
"amount": 4570,
"reason": "Клиент отменил заказ",
"refund_ref": "RET-1201-1"
}
{ "refunded": 4570, "remaining": 0, "repeated": false }
remaining — сколько по заказу числится оплаченным после этого возврата, а не
остаток одного счёта. Заказ оплачен частями и вернули только последнюю — там
будет сумма первой части, а заказ не закрывается, пока деньги по нему числятся.
Деньги уходят обратно через ту же кассу Kaspi, которой платили. Начисление после возврата попадает к вам в «разбор»: полный возврат снимает покрытие, и решить его судьбу — ваше дело, а не наше.
refund_ref обязателен, и вот почему
Это номер возврата в вашем учёте. Он нужен не нам, а вам: по нему мы отличаем «повтори, я не понял ответа» от «верни ещё раз».
Представьте обрыв связи на таймауте. Деньги уже вернулись, но ваш код ответа не
увидел и повторяет запрос. Без номера повтор получил бы «возвращать нечего» —
то есть отказ там, где всё получилось, и дальше вы возвращали бы второй раз
руками или не возвращали вовсе. С номером повтор вернёт тот же ответ, а в
нём "repeated": true.
Свой номер мы придумать не можем: по одной оплате бывает несколько частичных возвратов, и «возврат по этому заказу» их не различает.
Частичный возврат
amount меньше суммы оплаты — вернётся частично. Но учтите: после первого
возврата, даже частичного, счёт считается закрытым, и второй возврат по нему
уже не пройдёт. Возвращайте нужную сумму одним запросом.
После полного возврата заказ закрывается сам: статус cancelled, придут
события order.refunded и order.cancelled. Бизнесу разбирать нечего.
После частичного заказ уходит бизнесу на разбор: что делать с остатком,
решает человек. Исключение — возврат всей переплаты: деньги сошлись с ценой, и
заказ остаётся оплаченным (если возврат первой нашла сверка, заказ всё же уйдёт на разбор).
Ответы
| Код | Что значит |
|---|---|
200 |
Вернули. repeated: true — это ответ по вашему прежнему запросу, денег второй раз не трогали |
400 nothing_to_refund |
По заказу нет оплаченного счёта — возвращать нечего |
400 rejected |
Касса отказала. Текст отказа — в error, он от Kaspi |
404 order_not_found |
Такого заказа нет |
409 in_progress |
Возврат с этим номером ещё выполняется — повторите позже |
409 outcome_unknown |
Исход неизвестен: касса могла вернуть, а ответа нет. Повторяйте тем же refund_ref |
409 refund_ref_conflict |
Этот refund_ref уже использован для другого заказа или другой суммы |
501 not_available |
Возвраты у этой кассы не подключены |
Пока по заказу висит возврат без исхода (in_progress или outcome_unknown),
другого возврата по нему не заведём — ответ 409 in_progress. Иначе
строка учёта от второго возврата могла бы закрыть первый как успешный.
Чего мы не обещаем
Kaspi отказывает в возврате по своим правилам, и они не опубликованы. Отказ
приходит кодом -990000601 («Возврат отклонен») без объяснения причины. Две
причины, которые мы видели вживую:
- на счёте бизнеса в Kaspi меньше суммы возврата. Возврат списывается с этого счёта; если выручку уже вывели, а комиссия Kaspi списана, касса откажет даже по только что полученной оплате. Пополните счёт и повторите;
- оплату уже вернули вручную в приложении Kaspi. Не возвращайте одну оплату дважды — через API и руками.
Возраст платежа сам по себе помехой не оказался: двухсуточная оплата вернулась
без вопросов. Отказ -990000601 означает, что денег касса не трогала, — повтор
после пополнения счёта безопасен.
Текст отказа мы передаём дословно и ничего не додумываем: если касса сказала «нет», денег она не вернула.
Исход неизвестен (409 outcome_unknown)
Бывает, что ответа кассы нет: связь оборвалась посреди запроса, касса не ответила за минуту или у нас что-то сломалось уже после её ответа. Тогда деньги могли уйти, и сказать «отказ» было бы неправдой — ваш повтор пошёл бы в кассу второй раз и вернул бы одну оплату дважды.
Поэтому по такому номеру мы в кассу больше не ходим. Возврат, который касса
всё-таки провела, наша сверка находит в выписке Kaspi (раз в час) — и следующий
ваш запрос с тем же refund_ref получит 200 с repeated: true. Пока
возврата в выписке нет, ответ остаётся 409 outcome_unknown.
Что делать вам: повторять тем же номером время от времени и не заводить новый
refund_ref на ту же оплату. Если исход не прояснился за сутки — напишите нам.
Заказ без телефона покупателя (созданный без customer_phone) возвращается
так же, как с телефоном.
Прислать ссылку в WhatsApp
Заказ заведён, ссылка есть — но покупатель её ещё не видел. Этот вызов отправит ему сообщение в WhatsApp со ссылкой на оплату.
POST /api/v1/orders/YESH-1201/notify
{ "channel": "whatsapp" }
{ "sent": true, "channel": "whatsapp", "messageId": "wamid.HBgLNzc..." }
Ни телефона, ни текста в запросе нет — и не будет. Номер берётся из
customer_phone заказа, текст собираем мы. Иначе ваш ключ стал бы способом
писать кому угодно что угодно от нашего имени, и отвечать за это пришлось бы
нам обоим.
Значит, чтобы этот вызов работал, заказ должен быть заведён с
customer_phone. Без него ответ будет no_phone.
Что придёт покупателю
Счёт на оплату от KSA Visa.
Сумма: 4 570 ₸
Оплатить: https://kazpayment.kz/pay/9f2c1a7b
Ссылка ведёт на страницу оплаты KazPayment. Если вы ничего не заказывали,
просто не переходите по ней.
Название вашего бизнеса подставляется в текст, потому что по умолчанию отправитель — номер KazPayment, а не ваш.
Можно писать и со своего номера: для этого нужен свой WhatsApp Business Account в Meta и одобренные в нём шаблоны. Тогда в переписке стоит ваше имя, на репутацию вашего номера не влияют чужие рассылки, а счёт за сообщения Meta выставляет вам напрямую — наши 18 ₸ за сообщение при этом не списываются. Напишите нам, и мы подключим.
Переключиться обратно на наш номер можно в любой момент, настройки при этом сохраняются: возвращаться обычно приходится не от хорошей жизни — кончились деньги на счету Meta или протух токен, — и проходить настройку заново в такой момент было бы издевательством.
Если платят не нам
Бывает, что вы доводите человека до ЧУЖОЙ кассы: государственного портала,
партнёра, маркетплейса. Тогда передайте адрес в link — уйдёт другой шаблон,
который прямо говорит, что оплата пройдёт на стороннем сайте.
POST /api/v1/orders/YESH-1201/notify
{
"channel": "whatsapp",
"link": "https://payment.visitsaudi.com/checkout?id=afbb6785",
"amount": "210 SAR"
}
Адрес проверяется теми же правилами, что приёмник вебхуков: только https и
только публичное доменное имя — по ссылке пойдёт живой человек.
amount обязателен вместе с link — это сумма, которую человек заплатит
ТАМ, и знаете её только вы. Взять её из заказа нельзя: в заказе ваша цена, в
тенге, и к моменту такого сообщения она обычно уже оплачена — покупатель
прочитал бы «к оплате 0 ₸» рядом со ссылкой на чужой платёж. Строкой, а не
числом: платят не обязательно в тенге.
Это отдельное сообщение от счёта за вашу работу. По одному заказу законно уходят оба: сперва «оплатите оформление», потом «вот ссылка на сбор». Ограничение «одно сообщение» действует на каждый вид отдельно.
Такое сообщение уходит и по оплаченному заказу — в том и смысл: сбор на чужом портале обычно появляется уже после того, как вы получили свои деньги. Правило «по закрытому заказу не пишем» относится только к счёту за вашу работу.
Получатель всё так же берётся из заказа: писать можно своему покупателю, а не любому номеру.
Свой текст сообщения
Текст выше подходит магазину, но не всякому делу: где-то платят не «счёт», а работу по заявке, и рядом стоит сбор, который платится мимо нас. Под такое заводится отдельный шаблон — напишите нам, какой текст нужен.
Выбрать шаблон запросом нельзя, и это не забывчивость: шаблоны живут в нашем
аккаунте Meta и проходят нашу модерацию, а выбор из запроса означал бы, что
один магазин может отправить сообщение текстом другого. Шаблон назначается
вашему бизнесу один раз, дальше notify берёт его сам.
Подстановки у всех шаблонов одинаковые: название бизнеса, сумма, ссылка.
Одно сообщение на заказ
Повторный вызов по тому же заказу вернёт 200 и не отправит ничего:
{ "sent": false, "channel": "whatsapp", "reason": "already_sent" }
Прислать человеку один и тот же счёт дважды — верный способ настроить его против вас. Нужна свежая ссылка — заведите новый заказ.
Исключение — чужие ссылки (link): здесь «одно сообщение» считается на
ссылку, а не на заказ. Один заказ законно оплачивает работу за нескольких
людей, а платить ТАМ каждый будет по своей ссылке — и каждая уйдёт, по разу.
Повтор с той же ссылкой вернёт already_sent.
Когда не отправим
reason |
Что это значит |
|---|---|
already_sent |
По этому заказу уже писали (для link — эту же ссылку) |
no_phone |
У заказа нет customer_phone |
opted_out |
Покупатель ответил «СТОП» — мы обязаны молчать |
order_closed |
Заказ оплачен или отменён (только для счёта за вашу работу) |
no_channel |
Канал WhatsApp не настроен |
no_balance |
Не хватило денег на балансе — пополните счёт, настройки ни при чём |
no_pay_link |
Ссылку на оплату не удалось выпустить — повторите вызов |
send_failed |
WhatsApp отказал; причина у нас в журнале, напишите нам |
deferred |
WhatsApp был временно недоступен — сообщение в очереди, мы дошлём его сами. Повторять вызов не нужно |
Все эти случаи приходят с кодом 200: с вашей стороны ничего не сломалось, и
повторять запрос незачем. Настоящие ошибки (нет ключа, чужой заказ) отвечают
как обычно — 401, 404.
Сообщение платное, цена за него назначается отдельно от SMS и списывается с баланса. Ответ покупателя приходит нам, не вам: переписку в WhatsApp сервис не ведёт.
Написать покупателю в WhatsApp
Две ручки, и разница между ними — не в тексте, а в цене и в правилах.
POST /api/v1/whatsapp/order движение заказа — СЛУЖЕБНОЕ
POST /api/v1/whatsapp/cart забытая корзина — РЕКЛАМНОЕ
WhatsApp вне суточного окна принимает только заранее одобренные Meta шаблоны, и Meta делит их на служебные и рекламные. Служебное — про то, что человек уже начал: заказ, платёж, доставка. Рекламное зовёт начать. Рекламное стоит в несколько раз дороже, и считается оно по своему тарифу.
Движение заказа
{ "phone": "+7 708 214 77 03", "order": "YESH-1201", "state": "ждёт оплаты", "lang": "kk" }
state — готовая строка на языке покупателя: «курьер в пути», «можно
забирать». Этапы у магазинов разные, и перевести их на человеческий язык
можете только вы.
lang необязателен. Шаблона на этом языке может не оказаться — тогда
напишем языком по умолчанию и скажем каким: в ответе приходит
templateLang. Промах по языку у Meta означает не «другой язык», а
«шаблон не найден», то есть молчание.
Забытая корзина
{ "phone": "+7 708 214 77 03", "items": "3 блюда", "total": "4 950 ₸", "lang": "ru" }
Номера заказа здесь нет — заказа ещё нет, в этом и разница.
Согласие на рекламу проверяете вы. Мы ваших покупателей не видим и знать, кто на что соглашался, не можем. Жалобы на рекламу без согласия бьют по рейтингу номера, с которого уходят и ваши служебные сообщения.
Назвать рекламное сообщение служебным, чтобы заплатить меньше, нельзя: вид решает адрес ручки, а не поле в запросе.
Ответ
{ "messageId": "wamid.HBg...", "priceKzt": 50, "template": "cart_reminder_v1", "templateLang": "ru" }
priceKzt — сколько списали на самом деле. Списывается до отправки:
не хватает — 402 no_balance, ничего не уходит; WhatsApp отказал (502 provider_refused) — деньги возвращаются на баланс.
Баланс и пополнение
С баланса списываются SMS, WhatsApp и коды подтверждения. Он общий для кабинета и API.
SMS — за каждую часть, как берёт оператор: до 70 знаков кириллицей (67 в длинном сообщении) или до 160 латиницей (153) — одна часть. Это касается и рассылок, и напоминаний из кабинета: под текстом рассылки видно, сколько SMS он займёт.
GET /api/v1/balance
# → {"balance_kzt":1200,"exempt":false,
# "prices":{"sms":15,"sms_marketing":25,"whatsapp":12,"whatsapp_marketing":50,"otp":20},
# "entries":[{"id":"…","amount_kzt":-15,"reason":"sms_debit","created_at":"…"}]}
exempt: true — бизнес освобождён от платы: сообщения уходят и при нулевом остатке.
prices — цены в тенге: сообщения служебные и рекламные, otp — код подтверждения. entries — последние проводки, новые сверху;
положительная сумма — зачисление.
Комиссии с оборота у KazPayment нет. Ручка GET /api/v1/balance/commission
удалена 08.11.2026 и отвечает 404.
Пополнить:
POST /api/v1/balance/topup
{ "amount_kzt": 5000 }
# → {"sent":true,"charge_id":"…"}
sent: true значит, что счёт принят в работу: он уйдёт в Kaspi на номер владельца обычно
в течение минуты. Баланс вырастет после оплаты, ключ сам денег не списывает.
| Статус | code |
Что значит |
|---|---|---|
| 400 | invalid_request |
amount_kzt — не целое число от 1 до 10 000 000 |
| 409 | not_live |
бизнес в тестовом режиме или в архиве: настоящие деньги ему не зачислить |
| 409 | no_tariff |
у бизнеса нет тарифа или он отменён |
| 409 | tariff_paused |
подписка на тариф приостановлена |
| 409 | no_kaspi_phone |
не сохранён номер Kaspi для счетов |
| 409 | topup_pending |
есть неоплаченный счёт на эту же сумму за последние сутки |
| 501 | not_available |
баланс или цены сейчас недоступны |
topup_pending защищает от двойного счёта при повторе после таймаута, в том числе при
одновременных вызовах и в кабинете. В ответе есть charge_id и amount_kzt уже
выставленного счёта. В песочнице остаток нулевой, а пополнение отвечает not_live.
Ключ платформы: завести продавца
Для приложения, которое работает за своих продавцов. Право выдаёт оператор KazPayment вручную, ключ обычного бизнеса здесь не работает, и самому подключить его нельзя.
curl -X POST https://kazpayment.kz/api/v1/platform/sellers \
-H "Authorization: Bearer $APP_KEY" -H 'Content-Type: application/json' \
-d '{
"external_ref": "seller-1042",
"phone": "+77001234567",
"email": "shop@example.kz",
"kaspi_phone": "+77001234568",
"name": "Магазин Асель",
"offer": {"version": "02.11.2026", "accepted_at": "2026-11-07T10:15:00Z", "ip": "203.0.113.7"}
}'
| Поле | Смысл |
|---|---|
external_ref |
номер продавца у вас, до 100 символов. Повтор с теми же phone и email вернёт того же продавца |
phone, email |
владелец. Подтвердить их должны вы: кодов мы не шлём |
kaspi_phone |
необязателен, номер для счетов. Не передан — счета идут на phone. Сменить его повтором нельзя: seller_conflict |
name |
необязательно. Не передано — название временно равно телефону |
offer |
version — дата редакции оферты KazPayment вида 02.11.2026, accepted_at — время ISO 8601 с часовым поясом, ip — адрес продавца. Галочку показываете вы |
Ответ 201 (новый) или 200 (повтор): {"tenant_id": "…", "mode": "live"}.
Дальше работайте с ним обычными ручками, ключом приложения и заголовком
x-kazpayment-tenant: <tenant_id>.
Вебхук оплат продавца (PUT /api/v1/webhook) ставится так же. Адрес у бизнеса один:
ваш PUT и правка продавца в кабинете перезаписывают друг друга. Если адрес поставили вы,
то при отзыве продавцом доступа или архивации приложения он снимается вместе с
неотправленными событиями; после возврата доступа поставьте его заново. После отзыва
ключ для этого продавца не принимается (401). Адрес, который продавец поставил сам,
остаётся. Кто поставил адрес, видно в GET /api/v1/webhook: поле setByApp
({"slug", "name"} или null).
mode: "test" — бизнес заведён, но тариф Free не подключился. Повторите тот же вызов
и не заводите заказы, пока не придёт live: бизнес с заказами повтор в бой не переведёт,
это разбирает поддержка.
| Статус | code |
Что значит |
|---|---|---|
| 400 | invalid_request |
поле неверное или его нет |
| 401 | unauthorized |
ключ не принят или нет права заводить продавцов |
| 401 | app_revoked |
продавец закрыл вашему приложению доступ |
| 409 | account_exists |
телефон или почта уже есть в KazPayment: продавцу надо самому впустить ваше приложение в кабинете |
| 409 | seller_conflict |
этот external_ref уже у продавца с другим телефоном, почтой или номером Kaspi |
| 409 | seller_deleted |
продавец удалил бизнес; заново его завести нельзя |
| 429 | rate_limited |
слишком часто, см. retryAfterSeconds |
Продавцу кабинет необязателен. Понадобится — откройте его ссылкой (см. «Вход продавца в
кабинет» ниже) или продавец задаст пароль через «Забыли пароль» по этой почте. В кабинете он может и выставить ваше приложение: на следующем вызове
вы получите 401.
Подключить кассу Kaspi продавца
Только для продавцов, заведённых этим приложением. Номер и код из SMS вводит сам продавец у вас на сайте.
| Шаг | Вызов | Тело | Ответ |
|---|---|---|---|
| 1 | POST /api/v1/platform/sellers/{tenant_id}/kaspi/start |
нет | {"process_id": "…"} |
| 2 | POST …/kaspi/phone |
{"process_id", "phone"} |
{"sms_sent", "kaspi_says", "app_outdated"} |
| 3 | POST …/kaspi/otp |
{"process_id", "otp"} |
{"connected": true, "org_name": "…"} |
sms_sent: false: покажите продавцу kaspi_says. app_outdated: true — это наша
сторона, продавцу делать нечего, повторите позже.
Вход живёт в памяти сервера и после неверного кода не продолжается: на otp_rejected и
process_expired пройдите с первого шага. Состояние кассы смотрите в GET /api/v1/kaspi.
| Статус | code |
Что значит |
|---|---|---|
| 404 | seller_not_found |
не ваш продавец, или он закрыл вам доступ |
| 400 | invalid_phone |
номер не разобран |
| 409 | already_connected |
касса уже работает: вход её не перебивает |
| 422 | otp_rejected |
Kaspi не принял код |
| 422 | process_expired |
вход потерян, например сервер перезапускался |
| 429 | rate_limited |
не больше 30 вызовов в час на продавца и 5 кодов в час на номер: Kaspi закрывает номер за частые входы |
| 503 | kaspi_unavailable |
Kaspi не отвечает, повторите позже |
Вебхук приложения: беда у продавца
Один адрес на всех ваших продавцов. Вебхук бизнеса (PUT /api/v1/webhook) остаётся его
собственным и про оплаты заказов.
| Вызов | Тело | Ответ |
|---|---|---|
PUT /api/v1/platform/webhook |
{"url": "https://…"} |
{"url", "secret"}. Секрет показывается один раз, новый адрес меняет его |
GET /api/v1/platform/webhook |
нет | {"url", "last_delivery"} или 404 webhook_not_configured. В last_delivery статус, попытки и ошибка последней доставки: о смерти приёмника мы больше никак не сообщаем |
DELETE /api/v1/platform/webhook |
нет | {"removed": true}, очередь неотправленного тоже снимается |
POST /api/v1/platform/webhook/test |
нет | {"queued": true}, придёт webhook.test |
Подпись, попытки и таймауты те же, что у вебхука бизнеса. Тело события:
{"event_id": "…", "event": "seller.kaspi_disconnected", "occurred_at": "2026-11-07T20:15:00.000Z", "tenant_id": "…"}
event |
Что значит |
|---|---|
seller.kaspi_disconnected |
сессия кассы истекла: заказы не оплачиваются, пока продавец не войдёт заново |
seller.subscription_stopped |
тариф KazPayment приостановлен или отменён |
seller.subscription_resumed |
тариф снова действует: подписка возобновлена или продавец купил тариф заново. Первая покупка — не событие. Может прийти и без stopped, если тариф остановился до того, как продавец стал вашим |
Приходит только по продавцам, которых завели вы и которые не закрыли вам доступ. Событие
заводится в момент беды: адрес, заданный позже, о прошлом не узнает. Сверяйтесь по
GET /api/v1/kaspi. Повтор несёт тот же event_id.
Тариф продавца
Только для продавцов, заведённых этим приложением. Тариф называется кодом: free,
mini, start, business, pro, max. Коды не меняются; цены, лимиты и тексты
берите из списка, а не зашивайте. Цену приложение не задаёт.
| Вызов | Тело | Ответ |
|---|---|---|
GET /api/v1/platform/plans |
нет | [{"code", "name", "amount", "monthly_quota", "description", "features"}] — тарифы в продаже |
GET /api/v1/platform/sellers/{tenant_id} |
нет | состояние продавца, см. ниже |
POST …/sellers/{tenant_id}/subscription |
{"plan": "mini", "pay_method": "kaspi"} |
{"plan", "starts_on"}. Купить, когда действующего тарифа нет |
PUT …/sellers/{tenant_id}/subscription |
{"plan": "start"} |
сменить действующий, см. ниже |
DELETE …/sellers/{tenant_id}/subscription/next |
нет | {"cancelled": true} — передумать насчёт меньшего тарифа |
POST …/sellers/{tenant_id}/subscription/invoice |
нет | счёт на оплату для безнала, см. ниже |
Состояние продавца:
{
"tenant_id": "…",
"kaspi_connected": true,
"subscription": {
"plan": "mini", "plan_name": "Мини", "amount": 4490, "status": "active",
"pay_method": "kaspi", "starts_on": "2026-11-07", "paid_until": "2026-12-06",
"next": {"plan": "free", "plan_name": "Free", "from": "2026-12-07"}
},
"usage": {"used": 7, "quota": 100}
}
subscription — null, если тариф не покупали. status — active, paused или
cancelled. paid_until — последний оплаченный день 30-дневного периода, null до
первой оплаты. next — меньший тариф, выбранный с конца периода, или null.
usage — оплаты в текущем окне лимита; quota: null — без предела или тариф не
действует. plan — null у тарифа, снятого с продажи: его код уже может быть у
нового тарифа, и PUT с ним перевёл бы продавца на новый.
Счёт за тариф уходит в Kaspi на номер продавца для счетов (kaspi_phone при
регистрации, иначе phone). Номер ставит тариф Free при регистрации; если Free не
подключился (mode: "test"), покупка ответит no_billing_phone: повторите регистрацию.
Бизнес с заказами в песочнице повтор не исправит, его разбирает поддержка. pay_method: "bank" — продавец платит безналом по
счёту на оплату, его выдаёт POST …/subscription/invoice:
{"invoice_no", "issued_at", "period", "amount", "plan_name", "due_date"}. Номер
присваивается при первом вызове, повтор возвращает тот же.
Смена PUT …/subscription работает как в кабинете. Больший тариф — сразу, с доплатой
за остаток периода: {"change": "now", "plan", "surcharge_kzt"}, счёт на доплату
уходит сам; 0 — доплачивать нечего. Меньший — с конца оплаченного периода, возврата
нет: {"change": "scheduled", "plan", "from"}. Тарифы одной цены меняет поддержка.
| Статус | code |
Что значит |
|---|---|---|
| 400 | invalid_request |
код тарифа неизвестен, тариф уже ваш, или проверка тарифа не пройдена (текст в error) |
| 404 | seller_not_found |
не ваш продавец, или он закрыл вам доступ |
| 404 | nothing_to_pay |
неоплаченного счёта за тариф нет |
| 409 | no_subscription |
смена без действующего тарифа: купите его POST |
| 409 | already_subscribed |
покупка при действующем тарифе: меняйте его PUT |
| 409 | subscription_paused |
тариф приостановлен: ни покупки, ни смены, его возобновляет поддержка. Придёт seller.subscription_resumed |
| 409 | no_billing_phone |
у продавца нет номера для счетов |
| 429 | rate_limited |
не больше 60 изменений и 600 чтений в час на продавца |
Вход продавца в кабинет
Пароля от кабинета у продавца, которого завели вы, нет. Нужен ему кабинет (посмотреть платежи, настроить то, чего нет у вас), — попросите ссылку и откройте её продавцу:
POST /api/v1/platform/sellers/{tenant_id}/login-link
→ 200 {"url": "https://kazpayment.kz/sso#…", "expires_at": "2026-11-08T12:02:00.000Z"}
Ссылка живёт две минуты и открывается один раз: просите её в момент, когда продавец
нажал «Открыть кабинет», и сразу ведите его туда (переход или новая вкладка), а не
храните и не отправляйте в сообщениях. Код входа стоит после #: его браузер серверу не
шлёт, и он не попадает в журналы. Сохранить в браузере вход по такой ссылке нельзя —
закрыл вкладку, и в следующий раз нужна новая.
Включил продавец в кабинете вход с кодом — после ссылки кабинет спросит код из приложения-аутентификатора. Ссылка заменяет пароль, но не второй шаг: ваш ключ не открывает кабинеты тех, кто поставил себе эту защиту.
Вход по ссылке записан в журнале входов как «Из приложения».
| Статус | code |
Что значит |
|---|---|---|
| 404 | seller_not_found |
не ваш продавец, или он закрыл вам доступ |
| 429 | rate_limited |
не больше 30 ссылок в час на продавца |
Написать покупателю в SMS
POST /api/v1/sms
{ "phone": "+7 708 214 77 03", "text": "Заказ YESH-1201 готов", "kind": "marketing" }
kind необязателен и по умолчанию service. Рекламные SMS стоят дороже
служебных — у оператора это разный трафик, с именем отправителя и с
требованием согласия абонента. Отличить одно от другого по тексту мы не
можем, поэтому вид называете вы.
Занизить вид технически можно, но бессмысленно: рекламная рассылка, названная служебной, упрётся в оператора связи, а не в нас.
→ 200 { "messageId": "123456", "priceKzt": 60, "parts": 2 }
Цена — за каждую часть SMS, как берёт оператор: до 160 знаков латиницей
или до 70 кириллицей — одна часть; длиннее — части по 153 и 67 знаков. Текст
принимается до 160 знаков; кириллицей это три части. parts — сколько
частей ушло, priceKzt — сколько списали на самом деле.
Деньги списываются до отправки. Не хватает на всё сообщение — 402 no_balance, и ничего не уходит. Оператор отказал — деньги возвращаются на
баланс тем же движением.
Номер — только казахстанский мобильный (700–708, 747, 750–751, 760–764,
771–778). На российские и платные номера +7 SMS не отправляем: 400 invalid_phone.
Узнать статус
GET /api/v1/orders/YESH-1201
→ 200 {"orderRef": "YESH-1201", "amount": 4500, "paidAmount": 4500,
"refundedAmount": 0, "status": "paid",
"invoiceText": "Заказ Пицца Маргарита · YESH-1201", "created": false}
invoiceText — что покупатель видит в счёте Kaspi (см.
Текст счёта в Kaspi).
refundedAmount — сколько по заказу вернули покупателю, откуда бы ни пришёл
возврат (API, кабинет, приложение Kaspi). После возврата заказ снова
pending, а paidAmount уменьшен; по refundedAmount вы отличите возврат от
оплаты, которая не дошла.
created в ответе статуса всегда false — поле общее с ответом создания,
по нему различают «завёл» и «нашёл» именно там.
Ссылки на оплату в ответе нет намеренно: её выпуск — запись в нашей базе, и отдавать её на каждый опрос значило бы плодить записи оттого, что вы просто спрашиваете «оплатили?».
Статусы
Их три, и других не будет:
| статус | что значит |
|---|---|
pending |
ещё не оплачен; смотрите paidAmount — часть денег могла прийти |
paid |
оплачен полностью |
cancelled |
заказ отменён — бизнесом в кабинете или вашей программой через /cancel; платить не нужно |
Наши внутренние состояния наружу не выходят: вам по ним ветвиться нечего, а нам они связали бы руки при первом же переименовании.
Когда статус станет paid
Обычно за секунды. У Kaspi нет вебхука и для нас самих, поэтому оплату мы
узнаём, спрашивая кассу. Пока покупатель на странице оплаты, она спрашивает
кассу каждые несколько секунд; увидела оплату — тут же сверяет заказ, ставит
paid и отправляет вам вебхук.
Если покупатель закрыл страницу, не дождавшись «Оплачено», оплату подхватит сверка с выпиской кассы — она идёт раз в час. Поэтому в худшем случае статус и вебхук приходят в пределах часа после оплаты.
Опрашивать статус чаще раза в минуту смысла нет; для мгновенной реакции на покупателя используйте свою страницу успеха, а закрытие сделки вешайте на вебхук или статус.
Вебхук: мы сами говорим, что оплата пришла
Вместо опроса — событие на ваш адрес. Как и весь API, вебхуки работают на любом тарифе, включая Free.
Настроить
PUT /api/v1/webhook
{"url": "https://shop.kz/kazpayment/hook"}
→ 200 {"url": "…", "secret": "9f2c…64 hex-символа"}
Требования к адресу: https, публичное доменное имя (IP, localhost и
внутренние имена отвергаются), без логина и #фрагмента. Те же правила — для
адреса, заданного в кабинете.
Перед каждой доставкой мы проверяем, куда имя указывает: если хоть один его
адрес частный (10.x, 192.168.x, 127.x и т. п.), событие не уходит, а в
GET /api/v1/webhook видно причину. Редиректам доставка не следует —
отвечайте с самого адреса приёмника.
Секрет показывается один раз — сохраните его: в базе лежит только
шифртекст. Повторный PUT (в том числе с тем же адресом) выпускает новый
секрет — это и есть ротация.
GET /api/v1/webhook — адрес и судьба последней доставки (status,
attempts, error): если доставки умирают, это видно здесь, а не только
владельцу в Telegram. DELETE — отключить; неотправленная очередь при этом
удаляется.
Проверить приёмник
POST /api/v1/webhook/test → 200 {"queued": true}
В течение минуты на ваш адрес придёт событие webhook.test — тем же путём и с
той же подписью, что и настоящие.
Событие
POST на ваш адрес, Content-Type: application/json:
{
"event_id": "3f6a…-uuid",
"event": "payment.received",
"occurred_at": "2026-08-24T11:58:00.000Z",
"order_ref": "YESH-1201",
"charge_id": "…",
"subscription_id": null,
"payer_id": null,
"amount": 4500,
"paid_amount": 4500,
"late": false
}
Как понять, за что заплатили. У заказа опознавательный знак — ваш же
order_ref. У абонемента его нет (null): счёт выставил планировщик, а не вы,
— зато заполнены subscription_id и payer_id, те же, что вернулись при
оформлении подписки. Одно из двух заполнено всегда:
| Что оплачено | order_ref |
subscription_id / payer_id |
|---|---|---|
| Заказ, заведённый через API | ваш номер заказа | null |
| Абонемент | null |
идентификаторы подписки и клиента |
| Начисление, заведённое в кабинете вручную | null |
заполнены, если оно по подписке |
| Оплата с ценника — раздел «Товары» в кабинете | код товара и хвост: Ab3dEfGh-1a2b3c4d |
как у заказа через API |
Последняя строка — заказы, которых ваш сайт не создавал: их заводит
покупатель, отсканировав постоянный QR товара (QR на товар).
Если ваш обработчик ищет заказ по order_ref у себя и не находит — ответьте
200 и пропустите событие: ошибка в ответ означает повторы доставки, а затем
отметку приёмника как сломанного.
occurred_at — момент денег, а не момент доставки. Персональных данных в
событии нет: ни имени, ни телефона — только идентификаторы и суммы.
Возврат — order.refunded
Приходит, когда по заказу вернули деньги — через API, в кабинете или в приложении Kaspi (тогда — как только сверка найдёт возврат в выписке, обычно в течение часа). Одно событие на заказ.
{
"event_id": "…",
"event": "order.refunded",
"occurred_at": "2026-10-06T09:10:00.000Z",
"order_ref": "YESH-1201",
"charge_id": "…",
"amount": 4500,
"paid_amount": 0,
"refunded_amount": 4500
}
occurred_at здесь — момент, когда событие заведено (в ту же секунду, что
возврат попал в наш учёт), и он один на все повторы доставки.
Смотрите на event. Событий несколько, и order.refunded тоже несёт
order_ref и amount: приёмник, который не проверяет event, отметит
заказ оплаченным по сообщению о возврате.
Отмена — order.cancelled
Приходит, когда заказ отменили — кто бы это ни сделал: ваша программа через
/cancel, владелец бизнеса в кабинете или конец дня
отгрузки. Одно событие на заказ.
{
"event_id": "…",
"event": "order.cancelled",
"occurred_at": "2026-11-02T09:10:00.000Z",
"order_ref": "YESH-1201",
"charge_id": "…",
"subscription_id": null,
"payer_id": null,
"amount": 4500,
"paid_amount": 0
}
occurred_at — момент отмены, один на все повторы доставки. Событие приходит и
по заказам, которые вы отменили сами, — так приёмнику не нужно помнить, кто
отменял.
Не приходит: при исправлении суммы в кабинете (долг не снят, а переписан) и по брошенным заказам с ценника — покупатель отсканировал QR товара и не заплатил; такие заказы заводил не ваш сайт.
Неполная оплата отменённого — payment.partial
Заказ уже отменили, а покупатель всё-таки заплатил по старому QR, причём не
всю сумму. Заказ остаётся cancelled и оплаченным не становится, но деньги
у бизнеса есть. Это не сигнал «отдавайте товар», а повод разобраться: попросить
доплату или вернуть деньги.
{
"event_id": "…",
"event": "payment.partial",
"occurred_at": "2026-11-12T09:10:00.000Z",
"order_ref": "YESH-1201",
"charge_id": "…",
"subscription_id": null,
"payer_id": null,
"amount": 4500,
"paid_amount": 2000,
"late": true
}
paid_amount — сколько всего пришло по заказу. Одно событие на заказ.
Оплата после отмены — late
У payment.received есть поле late. true — заказ к моменту оплаты был уже
отменён: покупатель заплатил по QR-коду, выданному до отмены (Kaspi не даёт
забрать такой код назад). Деньги пришли по-настоящему, и заказ стал paid.
Не закрывайте такую сделку молча: товара может уже не быть, — решите, выдать
заказ или вернуть деньги.
Такое событие может прийти и позже обычного — через час-другой после оплаты:
если мы закрыли код у себя, а Kaspi всё же провела по нему деньги, оплату
находит и проводит часовая сверка с выпиской Kaspi, а при неоднозначности —
сотрудник бизнеса в разделе «Расхождения». Событие то же самое, с тем же
order_ref; полагайтесь на него, а не на время.
Подпись
Заголовок X-Kazpayment-Signature: sha256=<hex> — HMAC-SHA256 от сырых байт
тела вашим секретом. Проверяйте ДО разбора JSON:
const crypto = require('node:crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
const got = req.headers['x-kazpayment-signature'] ?? '';
const ok = got.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
Запрос без верной подписи отбрасывайте: адрес приёмника не секрет, и без проверки любой желающий сможет прислать вам «оплату».
Ответ, повторы, дедупликация
Ответьте 2xx за 10 секунд — тело мы не читаем. Всё остальное (не-2xx, таймаут, редирект) считается недоставкой.
Повторы: через 1 мин → 5 мин → 30 мин → 2 ч → 8 ч → 24 ч. Семь попыток за
~полтора суток; дальше доставка помечается dead, владелец бизнеса получает
уведомление в Telegram, а в GET /api/v1/webhook виден last_error.
Повтор несёт тот же event_id. Держите таблицу обработанных event_id и
закрывайте сделку один раз — доставка «хотя бы однажды», второе прибытие того
же события штатно.
И наоборот: вебхук может не дойти вовсе (полтора суток ваш приёмник лежал) —
не делайте его единственным источником правды, статус заказа всегда можно
спросить GET /api/v1/orders/<ref>.
Мелочи для приёмника: тело события меньше килобайта; dead-событие само не
воскресает, но каждая НОВАЯ оплата — это новое событие со своим event_id,
их доставка идёт независимо.
Дослать недоставленные
POST /api/v1/webhook/resend → 200 {"requeued": 3}
Приёмник лежал дольше полутора суток, события стали dead — почините адрес
(PUT /api/v1/webhook) и вызовите это: все недоставленные за последние 30 дней
снова встанут в очередь с полным запасом попыток и уйдут на текущий адрес.
event_id прежний — если какое-то событие вы всё-таки получили, дедупликация
его отсеет. Данные заказа в теле — на момент отправки. Без настроенного
приёмника — 400 webhook_not_configured. В кабинете то же самое — кнопка
«Отправить недоставленные заново» в разделе «Интеграция».
Ограничение частоты
120 запросов в минуту на бизнес. Считается по бизнесу, а не по ключу: второй ключ предел не удваивает.
При превышении — 429:
{"error": "Слишком часто. Подождите и повторите.",
"code": "rate_limited", "retryAfterSeconds": 12}
Повторяйте не раньше, чем через retryAfterSeconds.
Ошибки
Тело ошибки всегда одно по форме:
{"error": "текст по-русски", "code": "invalid_request"}
error — человеку в ваши логи. Ветвиться в коде — только по code: тексты
мы меняем свободно, коды — никогда (переименовать код значит сломать ваш
switch).
code |
HTTP | когда | что делать |
|---|---|---|---|
invalid_request |
400 | тело не разобрано или значения вне допустимого | читать error, чинить запрос |
unauthorized |
401 | ключ не предъявлен или не принят — различает текст error |
проверить Authorization, при «Ключ не принят» выпустить новый |
forbidden |
403 | ключ не той роли либо не даёт доступа сюда | выпустить ключ integration |
free_order_limit |
403 | тариф Free: за месяц через API создано 500 заказов | перейти на тариф «Мини» или выше в кабинете: «Бизнес» → «Оплата», либо дождаться 1-го числа; повторять запрос бесполезно |
free_subscription_limit |
403 | тариф Free: за месяц создано 500 подписок | то же |
not_found |
404 | такого адреса нет | сверить путь с этим документом |
order_not_found |
404 | заказа с таким номером нет | завести его |
order_already_paid |
409 | отмена: заказ уже оплачен | вернуть деньги через /refund |
order_partially_paid |
409 | отмена: часть денег пришла, бизнес велел отказывать | вернуть полученное, затем отменить |
invoice_rejected |
422 | счёт на номер: Kaspi не принял счёт, чаще всего на номере нет Kaspi | предложить QR или другой номер |
invoice_already_paid |
422 | счёт на номер: прежний счёт уже оплачен, новый не ушёл | не предлагать оплату снова; обычно придёт вебхук payment.received, заказ остался открытым — решает бизнес |
webhook_not_configured |
404 на GET, 400 на POST /test | приёмник не настроен | сначала PUT /api/v1/webhook |
method_not_allowed |
405 | адрес есть, метод не тот | сверить метод |
rate_limited |
429 | превышен предел частоты | ждать retryAfterSeconds, повторить |
not_available |
501 | возможность не подключена у нас | написать нам |
internal |
500 | сломалось у нас | повторить позже; чинить нам, не вам |
Отказ по существу операции приходит как 422 со своим кодом — таких кодов
немного и они тоже стабильны: order_amount_differs (повтор номера с другой
суммой), «бизнес убран из работы» и подобные.
Пример: заказ в интернет-магазине
// 1. Покупатель оформил заказ у вас — заводим его у нас.
const r = await fetch('https://kazpayment.kz/api/v1/orders', {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
external_ref: order.id,
amount: order.total,
comment: order.title,
customer_phone: order.phone,
}),
});
const { payUrl } = await r.json();
// 2. Показываем страницу оплаты: отдельным окном или в iframe у себя.
window.location.href = payUrl;
// 3. Пока покупатель платит — спрашиваем статус раз в несколько секунд.
const { status } = await (
await fetch(`https://kazpayment.kz/api/v1/orders/${order.id}`, {
headers: { Authorization: `Bearer ${KEY}` },
})
).json();
if (status === 'paid') markPaid(order);
То же на Python
import requests
API = "https://kazpayment.kz/api/v1"
HEAD = {"Authorization": f"Bearer {KEY}"}
# Завести заказ
r = requests.post(f"{API}/orders", headers=HEAD, json={
"external_ref": order.id,
"amount": order.total,
"comment": order.title,
"customer_phone": order.phone,
}, timeout=15)
r.raise_for_status()
pay_url = r.json()["payUrl"]
# Спросить статус
status = requests.get(f"{API}/orders/{order.id}", headers=HEAD, timeout=15).json()["status"]
Приёмник вебхука на Flask — проверка подписи по сырому телу:
import hmac, hashlib
from flask import request, abort
@app.post("/kazpayment/hook")
def hook():
raw = request.get_data() # именно сырые байты
expected = "sha256=" + hmac.new(SECRET.encode(), raw, hashlib.sha256).hexdigest()
got = request.headers.get("X-Kazpayment-Signature", "")
if not hmac.compare_digest(expected, got):
abort(403)
event = request.get_json()
if event["event"] != "payment.received": # возврат и проверка — не оплата
return "", 200
if already_processed(event["event_id"]): # повтор — штатное дело
return "", 200
mark_paid(event["order_ref"], event["amount"])
return "", 200
То же на PHP
<?php
$ch = curl_init('https://kazpayment.kz/api/v1/orders');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer $KEY", 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'external_ref' => $order['id'],
'amount' => $order['total'],
'comment' => $order['title'],
]),
]);
$order = json_decode(curl_exec($ch), true);
header('Location: ' . $order['payUrl']);
Приёмник вебхука:
<?php
$raw = file_get_contents('php://input'); // до json_decode!
$expected = 'sha256=' . hash_hmac('sha256', $raw, $SECRET);
if (!hash_equals($expected, $_SERVER['HTTP_X_KAZPAYMENT_SIGNATURE'] ?? '')) {
http_response_code(403); exit;
}
$event = json_decode($raw, true);
// Событий несколько (оплата, возврат, проверка) — оплатой считаем только оплату.
if ($event['event'] === 'payment.received' && !alreadyProcessed($event['event_id'])) {
markPaid($event['order_ref']);
}
http_response_code(200);
Проверка без денег: песочница
У каждого бизнеса может быть песочница — его копия без денег, на любом тарифе, включая Free. Владелец заводит её в кабинете: «Подключения» → «Интеграция» → «Песочница для разработчиков» → «Создать песочницу». Кабинет переключается в песочницу; обратно — кнопкой «Вернуться в бизнес» на жёлтой плашке.
В песочнице API работает целиком, но денег нет:
- свои ключи — выпускаются в песочнице и начинаются с
kp_test_. Боевые ключи начинаются сkp_live_: перепутать их глазами трудно. Ключ песочницы в бою не работает, и наоборот — это разные бизнесы; - свой вебхук — настраивается в песочнице отдельно от боевого;
- оплату нажимаете вы: на странице
payUrlпесочницы есть жёлтый блок «Тестовый режим» с кнопками «Оплатить», «Отклонить» и «Оплатить другой суммой». Дальше всё идёт как в бою: сверка закрывает заказ, вебхук уходит на ваш адрес. «Другой суммой» — покупатель заплатил половину: заказ уходит бизнесу на разбор,payment.receivedне приходит; - сообщения уходят только владельцу — на его телефон, почту или Telegram. Покупателям из песочницы не пишется ничего: напоминания и ссылки на оплату на чужие номера остаются в журнале с пометкой «не отправлено»;
- пределов Free нет, денег и баланса нет, касса Kaspi не подключается, в бой песочница не переводится никогда.
Программной ручки «оплатить за клиента» в API нет намеренно: в бою такой не бывает, и код, написанный вокруг неё, пришлось бы переписывать. Кнопки на странице оплаты — другое дело: в бою там тоже стоит человек.
Исключение — коды подтверждения по SMS: они настоящие и в песочнице недоступны (SMS стоят денег, а баланса у песочницы нет).
Что стоит проверить в песочнице до боевого запуска:
- повтор создания заказа с тем же
external_ref— должен вернуть тот же заказ иcreated: false; - повтор с другой суммой —
422 order_amount_differs; - заказ с неверным ключом —
401; - ваш приёмник вебхука — через
POST /api/v1/webhook/test, затем «Оплатить» на странице заказа; - отказ и чужая сумма — «Отклонить» и «Оплатить другой суммой»;
- отмена заказа —
/cancelи событиеorder.cancelled; - поведение при
429: искусственно упереться в лимит и убедиться, что вы ждётеretryAfterSeconds, а не долбите повторами.
Абонементы: клиент и подписка
Заказ — это разовая оплата. Если ваш бизнес продаёт абонементы (школа, зал, курсы), нужно другое: завести человека, подписать его на тариф, и дальше начисления с напоминаниями пойдут сами — как из кабинета, только программно.
Типичный путь интеграции с вашей CRM: ученик записался → вы заводите клиента → оформляете подписку → раз в месяц KazPayment сам выставляет счёт и напоминает, а вы узнаёте об оплате вебхуком.
Тарифы бизнеса
curl https://kazpayment.kz/api/v1/plans -H "Authorization: Bearer $KEY"
# → {"plans":[{"id":"…","name":"Абонемент","amount":15000,"interval":"monthly","cycle_days":null,
# "due_weekday":null,"due_day":1,"custom_from":null,"custom_to":null,"prorate":"full",
# "status":"active","unpaid_policy":{"own":false}}]}
Когда тариф выставляет счёт:
| Тариф | Поля | Пример |
|---|---|---|
weekly |
due_weekday — день недели, 1 — понедельник … 7 — воскресенье |
2 — по вторникам |
monthly |
due_day — число месяца |
5 — 5-го числа |
quarterly, yearly |
— | в первый день квартала или года |
| «Свой» период | custom_from, custom_to — ММ-ДД, каждый год |
09-01…05-31 — учебный год |
Кто подписался посреди периода, получает счёт в день начала подписки. Если в
месяце нет такого числа (31-е в феврале), счёт приходит в последний день месяца.
У «Своего» периода вне его дат (для учебного года — летом) счетов нет; в
interval у него yearly.
prorate — первый счёт клиента, пришедшего посреди периода: full — полная
сумма, months — за оставшиеся месяцы (месяц прихода целиком; у квартала, года
и «Своего»), days — за оставшиеся дни. Со следующего периода сумма полная.
cycle_days — длина периода тарифа «от дня оплаты»: 7, 30, 90 или
365. Следующий счёт по такому тарифу приходит, когда закончится оплаченный
период, а не в фиксированный день месяца. null — тариф идёт по календарю
(interval: неделя, месяц, квартал, год).
Тарифы заводятся в кабинете («Клиенты и подписки» → «Тарифы») — программно их не создать намеренно: цена услуги для клиентов бизнеса это решение владельца, а не интеграции.
Завести клиента
В API клиент называется payer (адрес /api/v1/payers); в кабинете он
появится в разделе «Клиенты».
curl -X POST https://kazpayment.kz/api/v1/payers \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"phone":"+7 701 111 22 33","full_name":"Иванов Иван","email":"ivan@example.kz","lang":"ru"}'
# → {"id":"…","phone":"77011112233","full_name":"Иванов Иван","created":true}
Повтор безопасен. Ключ — телефон: тот же номер (в любом написании) вернёт
существующего человека с created: false, а не заведёт второго. Сетевой сбой и
повторная отправка не создадут дубль, у которого потом окажется свой абонемент.
lang — язык напоминаний клиенту (ru или kk), по умолчанию ru.
Оформить подписку
curl -X POST https://kazpayment.kz/api/v1/subscriptions \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"payer_phone":"+77011112233","plan_id":"…","starts_on":"2026-09-01"}'
# → {"id":"…","payer_phone":"77011112233","plan_name":"Абонемент","amount":15000,"status":"active"}
starts_onнеобязателен — по умолчанию сегодня.ends_onнеобязателен — без него абонемент бессрочный.amountнеобязателен — своя цена для этого клиента; без него он платит по тарифу и автоматически следует его изменениям.
Повтор с тем же клиентом и тем же тарифом вернёт действующую подписку
(200), а не заведёт вторую: два абонемента означали бы два счёта в месяц
одному человеку.
Долг за перерыв. Если бизнес включил в кабинете «При новой подписке выставлять долг за пропущенные периоды», а прежнюю подписку этого клиента отменили из-за неоплаты (причина «не отвечает»), первый счёт новой подписки включит пропущенные периоды — не больше заданного бизнесом предела. Длина периода и цена берутся из тарифа новой подписки. Сколько периодов вошло, видно в ответе:
{"id":"…","payer_phone":"77011112233","plan_name":"Абонемент","amount":15000,"status":"active","missed_periods":2}
missed_periods: 0 — долга нет. Повторное оформление за тот же перерыв долг
второй раз не выставит.
Посмотреть подписки
curl "https://kazpayment.kz/api/v1/subscriptions?payer_phone=%2B77011112233" \
-H "Authorization: Bearer $KEY"
Без payer_phone вернутся все подписки бизнеса.
Остановить или возобновить
curl -X PUT https://kazpayment.kz/api/v1/subscriptions/<id> \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"status":"cancelled"}'
Значения: active, paused, cancelled. Это не удаление — история начислений
и оплат остаётся, просто новых требований денег человеку не уходит.
Отмена (cancelled) закрывает и уже выставленные неоплаченные счета этой
подписки: счёт в Kaspi снимается, напоминания прекращаются. Частично оплаченный
счёт не закрывается (часть денег получена, разбор за бизнесом), но и не
перевыставляется. Пауза (paused) счета не закрывает.
Если для тарифа действует правило «Отменять подписку» при неоплате (общее правило тарифов или отдельное правило тарифа, см. Настройки бизнеса), подписка отменится сама через заданное число дней после срока неоплаченного счёта, с теми же последствиями.
В той же настройке бизнес может выбрать «Добавлять долг в следующий счёт»:
тогда неоплаченный счёт закрывается в день, когда заводится счёт за следующий
период, и его сумма входит в новый. Если вы следите за заказами подписки
через GET, имейте в виду: закрытый так счёт перестаёт быть открытым, а
новый приходит на большую сумму. Или «Не считать пропущенное долгом» — тогда
неоплаченный счёт закрывается через заданное число дней, подписка продолжается.
Долг и отмена в ответе
У каждой подписки в ответах GET и POST:
debt_amount— просроченный неоплаченный остаток по подписке, ₸;overdue_charges— сколько таких счетов;cancel_reason— почему отменена:no_response(в том числе отменилась сама по неоплате),price,left,quality,other;null— не отменена;cancelled_at— когда отменена.
Настройки бизнеса
То же, что владелец настраивает в кабинете, доступно по ключу.
Если клиент не оплатил подписку — общее правило тарифов («Тарифы» в кабинете; оно же видно в «Напоминаниях»):
curl https://kazpayment.kz/api/v1/settings/unpaid-policy -H "Authorization: Bearer $KEY"
# → {"mode":"debt","days":null,"missed_periods_max":null,"reissue_pause_days":3}
curl -X PUT https://kazpayment.kz/api/v1/settings/unpaid-policy \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"mode":"merge","missed_periods_max":3}'
mode:
| Значение | Что происходит |
|---|---|
debt |
Долг копится отдельными счетами, напоминания идут (по умолчанию) |
merge |
Долг копится и входит в счёт следующего периода одной суммой |
forgive |
Через days дней после срока неоплаченный счёт закрывается, подписка продолжается |
cancel |
Через days дней после срока подписка отменяется, без напоминаний о просрочке |
days (1–90) обязателен для forgive и cancel. merge и forgive
работают на календарных тарифах. Все режимы, кроме debt, касаются счетов со
сроком после выбора режима и ушедших клиенту в Kaspi.
missed_periods_max (1–24 или null) — сколько пропущенных периодов включать
в первый счёт новой подписки клиента, чью прежнюю отменили из-за неоплаты.
reissue_pause_days (0–30, по умолчанию 3) — через сколько дней выставить новый
счёт, если прежний исчез из Kaspi без оплаты; 0 — сразу. Счёт уходит утром по
времени бизнеса. Заказ и подписка всё это время можно оплатить по ссылке.
Отгрузок не касается: у них своё расписание перевыставления.
Поля, которых нет в запросе, не меняются.
Отдельное правило тарифа. У тарифа-подписки может быть своё правило — тогда для его подписок оно действует вместо общего:
curl https://kazpayment.kz/api/v1/plans/<plan_id>/unpaid-policy -H "Authorization: Bearer $KEY"
# → {"own":false} — действует общее правило тарифов
curl -X PUT https://kazpayment.kz/api/v1/plans/<plan_id>/unpaid-policy \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"own":true,"mode":"cancel","days":5,"missed_periods_max":null}'
# вернуть к общему: -d '{"own":false}'
Отдельное правило задаётся целиком (mode обязателен, days — для forgive
и cancel). Возврат к общему стирает поля тарифа. В GET /api/v1/plans у
тарифов-подписок есть поле unpaid_policy в том же виде.
Счета по расписанию у нового бизнеса стоят на паузе, пока владелец не нажмёт «Начать выставлять счета»:
curl https://kazpayment.kz/api/v1/settings/auto-billing -H "Authorization: Bearer $KEY"
# → {"paused":true,"subscriptions":12,"kassa_connected":true}
curl -X POST https://kazpayment.kz/api/v1/settings/auto-billing/start -H "Authorization: Bearer $KEY"
Название бизнеса и как обращаться к владельцу — то же, что владелец вводит в кабинете сразу после регистрации («Расскажите о себе»):
curl https://kazpayment.kz/api/v1/settings/profile -H "Authorization: Bearer $KEY"
# → {"business_name":"+7 707 950 75 19","contact_name":null}
curl -X PUT https://kazpayment.kz/api/v1/settings/profile \
-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"business_name": "Магазин Айгуль", "contact_name": "Айгуль"}'
# → {"business_name":"Магазин Айгуль","contact_name":"Айгуль"}
Можно передать одно поле, второе останется прежним. business_name — от 2 до
100 символов, contact_name — от 2 до 60; переводы строк и двойные пробелы
схлопываются. contact_name: null значит, что владелец ещё не отвечал: пока
оно пустое или название равно номеру телефона, кабинет перед входом покажет
владельцу эту форму. Если продавца заводит ваше приложение, задайте оба поля
сразу, и форма его не встретит.
Ошибки
code |
Что случилось |
|---|---|
invalid_phone |
Номер не похож на казахстанский |
payer_not_found |
Клиента с таким телефоном у бизнеса нет |
plan_not_found |
Тарифа с таким plan_id нет |
Подтверждение телефона кодом (SMS OTP)
Отдельная возможность, не связанная с заказами: вы отправляете код на номер своего пользователя и проверяете введённое им значение. Полезно, когда у вас своя регистрация или подтверждение действия, а поднимать договор с оператором рассылки ради этого не хочется.
Каждый код — настоящая SMS, и она списывается с баланса вашего бизнеса. Цена кода видна в кабинете: «Бизнес» → «Оплата»; она отдельная и может отличаться от цены обычных SMS сервиса. Проверка кода бесплатна.
Отправить код
curl -X POST https://kazpayment.kz/api/v1/otp/request \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"phone":"+7 701 111 22 33","idempotency_key":"login-attempt-7f31"}'
# → {"requestId":"a1b2c3…"}
Номер принимается в любом привычном виде — +7 701…, 8 701…, 7701…;
непохожее на казахстанский мобильный номер значение отклоняется с
invalid_phone. Российские и платные номера +7 (9xx, 809) тоже
отклоняются: SMS туда стоят в разы дороже.
Цена кода списывается до отправки; если код не ушёл (провайдер отказал,
номер упёрся в предел частоты), деньги возвращаются на баланс.
requestId сохраните: он нужен для проверки и живёт недолго.
idempotency_key необязателен для обратной совместимости, но его следует
передавать всегда. Это уникальная строка длиной 8–128 символов для одной
попытки отправки; допустимы латинские буквы, цифры, ., _, :, -.
Если HTTP-ответ потерялся, повторите запрос с тем же ключом и тем же номером:
KazPayment вернёт прежний requestId без новой SMS и нового списания. Для
осознанной повторной SMS создайте новый ключ. Повторное использование ключа
с другим номером отклоняется с HTTP 409 и кодом idempotency_conflict.
Что увидит ваш пользователь
Текст SMS — ваш, а не наш:
Zimbir: ваш код 0000
Имя берётся из кабинета: «Подключения» → «Интеграция» → «Имя в SMS с кодом». Не
задали — код придёт безымянным: Ваш код: 0000. Имени сервиса в этом
сообщении не будет ни в одном из случаев: человек подтверждает телефон у ВАС,
и код от незнакомой ему конторы он, скорее всего, вводить не станет.
Имя — не длиннее 20 знаков. Причина денежная: кириллическая SMS вмещает 70 знаков, длиннее она уходит двумя частями и стоит вдвое дороже, а с вас списывается цена одной.
Проверить код
curl -X POST https://kazpayment.kz/api/v1/otp/verify \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"requestId":"a1b2c3…","code":"123456"}'
# → {"validated":true,"phone":"77011112233"}
validated: false — код не подошёл; phone в этом случае null. Привязывайте
номер из ответа, а не тот, что прислал вам пользователь: это единственный
номер, про который мы утверждаем, что он подтверждён.
Проверить можно только код, выданный вашим ключом (ключом этого же
бизнеса) в течение суток. Чужой или неизвестный requestId — 404 not_found,
и попытка ввода при этом не тратится.
Долг и отмена в ответе
У каждой подписки в ответах GET и POST:
debt_amount— просроченный неоплаченный остаток по подписке, ₸;overdue_charges— сколько таких счетов;cancel_reason— почему отменена:no_response(в том числе отменилась сама по неоплате),price,left,quality,other;null— не отменена;cancelled_at— когда отменена.
Настройки бизнеса
То же, что владелец настраивает в кабинете, доступно по ключу.
Если клиент не оплатил подписку («Напоминания» в кабинете):
curl https://kazpayment.kz/api/v1/settings/unpaid-policy -H "Authorization: Bearer $KEY"
# → {"mode":"debt","days":null,"missed_periods_max":null}
curl -X PUT https://kazpayment.kz/api/v1/settings/unpaid-policy \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"mode":"merge","missed_periods_max":3}'
mode:
| Значение | Что происходит |
|---|---|
debt |
Долг копится отдельными счетами, напоминания идут (по умолчанию) |
merge |
Долг копится и входит в счёт следующего периода одной суммой |
forgive |
Через days дней после срока неоплаченный счёт закрывается, подписка продолжается |
cancel |
Через days дней после срока подписка отменяется, без напоминаний о просрочке |
days (1–90) обязателен для forgive и cancel. merge и forgive
работают на календарных тарифах. Все режимы, кроме debt, касаются счетов со
сроком после выбора режима и ушедших клиенту в Kaspi.
missed_periods_max (1–24 или null) — сколько пропущенных периодов включать
в первый счёт новой подписки клиента, чью прежнюю отменили из-за неоплаты.
Поля, которых нет в запросе, не меняются.
Счета по расписанию у нового бизнеса стоят на паузе, пока владелец не нажмёт «Начать выставлять счета»:
curl https://kazpayment.kz/api/v1/settings/auto-billing -H "Authorization: Bearer $KEY"
# → {"paused":true,"subscriptions":12,"kassa_connected":true}
curl -X POST https://kazpayment.kz/api/v1/settings/auto-billing/start -H "Authorization: Bearer $KEY"
Ошибки
code |
Что случилось |
|---|---|
invalid_phone |
Номер не похож на казахстанский мобильный |
no_balance |
На балансе бизнеса не хватает на одну SMS — код не отправлен |
daily_cap_reached |
Исчерпан суточный предел кодов (300 на бизнес) |
rate_limited |
Слишком часто; ждите retryAfterSeconds |
not_available |
Отправка кодов не подключена на стороне сервиса |
Пределы и почему они такие
- Минута между кодами на один номер и не больше пяти в час. Чтобы вашей формой нельзя было завалить человека сообщениями.
- 300 кодов в сутки на бизнес — общий предел на все ваши ключи. Это защита от заевшего цикла и перебора номеров: каждый вызов стоит денег, и без потолка одна ошибка в коде выжигает баланс за ночь. Мало для вашей нагрузки — напишите, поднимем.
- Баланс — последняя черта: нет денег, нет отправки.
Имя отправителя в SMS — зарегистрированное имя KazPayment: у Beeline это наше альфа-имя, у остальных операторов имя выбирается автоматически по договору с оператором. Подставить своё название интегратор не может. Учитывайте это в тексте формы: человек увидит отправителем сервис, а не ваш бренд. Нужно собственное имя отправителя — напишите, это отдельно оформляется у оператора.
Показатели бизнеса
Те же числа, что в кабинете на странице «Показатели»: как клиенты платят, в сравнении с прошлым месяцем и тем же месяцем год назад. Только чтение, денег не стоит, доступно на всех тарифах.
Оплаты
curl "https://kazpayment.kz/api/v1/metrics?month=2026-10" -H "Authorization: Bearer $KEY"
month — ГГГГ-ММ в поясе бизнеса; без него — текущий месяц. В ответе
months — 13 месяцев по возрастанию: выбранный последним, первым — тот же
месяц год назад. И late — счета выбранного месяца, оплаченные позже срока, не
оплаченные до сих пор или закрытые без оплаты (closed_on), сначала самые
долгие; в списке не больше 100, всего — late_total.
В SDK — getMetrics({ month }); другие разделы — getMetrics({ part: 'clients', month }).
{
"month": "2026-10",
"months": [
{"month": "2026-10", "partial": false, "billed": 30000, "collected": 24000,
"collection_rate": 0.8, "due_count": 3, "on_time_count": 1, "on_time_rate": 0.3333,
"late_avg_days": 3, "received": 22000, "paying_clients": 3, "avg_per_client": 7333}
],
"late": [
{"charge_id": "…", "payer_id": "…", "payer_name": "Айгуль", "plan_name": "Абонемент",
"amount": 10000, "due_date": "2026-10-15", "paid_on": null, "closed_on": null, "days_late": 20}
],
"late_total": 1
}
| Поле | Что значит |
|---|---|
billed |
Сколько потребовали по счетам со сроком в этом месяце, ₸ |
collected |
Сколько из этого оплачено на сегодня, ₸ |
collection_rate |
collected ÷ billed, от 0 до 1 |
due_count, on_time_count, on_time_rate |
Счетов со сроком в месяце; из них оплачены полностью не позже срока; доля |
late_avg_days |
На сколько дней в среднем опоздали те, кто оплатил после срока |
received |
Деньги, пришедшие в этом месяце по регулярным счетам, за вычетом возвратов, ₸ |
paying_clients, avg_per_client |
Сколько клиентов платили в месяце; received на одного, ₸ |
partial |
Месяц ещё идёт |
Что считается:
- регулярные счета — подписки и счета, выставленные человеку вручную. Заказы магазина, QR на товары и отгрузки сюда не входят: у заказа «срок» — это минута создания;
- месяц — по сроку оплаты, и только прошедшие сроки: счёт со сроком
25-го не может быть «не оплачен вовремя» 10-го, а в сам день срока клиент
ещё вправе заплатить.
received— по дате денег; - отменённый до срока счёт (или заменённый исправлением) не считается —
бизнес передумал требовать. Закрытый без оплаты после срока (вручную,
правила
forgiveиcancel, отмена подписки) считается неоплаченным: это долг, который не собрали; - счёт, вошедший в общий счёт долга (
merge), остаётся в своём месяце и считается оплаченным, когда оплачен общий; у общего в его месяце — только своя часть; - частично оплаченный к сроку — не в срок;
- возвращённый счёт считается оплаченным: клиент заплатил, деньги вернули вы.
Возвраты уменьшают только
received; - нет счетов — доли
null, а не 0.
Клиенты: приток и отток
curl "https://kazpayment.kz/api/v1/metrics/clients?month=2026-10" -H "Authorization: Bearer $KEY"
Движение регулярных подписок (абонемент, пакет, «раз в N дней»): сколько действовало на первое число, пришло, вернулось, ушло и закончилось по сроку. Подписка, а не клиент: у родителя с двумя детьми — две подписки.
{
"month": "2026-10",
"months": [
{"month": "2026-10", "partial": false, "at_start": 6, "added": 1, "returned": 1,
"left": 3, "left_of_start": 3, "ended": 1, "churn_rate": 0.5, "attendance_rate": 0.75}
],
"reasons": {"price": 1, "no_pay": 2},
"left_list": [
{"subscription_id": "…", "payer_name": "Айгуль", "plan_name": "Абонемент",
"why": "price", "left_on": "2026-10-11", "last_paid_on": "2026-09-05"}
]
}
- ушла (
left) — отменена или два периода подряд не оплачены (что раньше). Неоплачен — открыт, закрыт без оплаты после срока или вошёл в неоплаченный общий счёт. Дата ухода по неоплате — срок второго из двух подряд. Оплатил что-то позже — уже не ушедший; - у тарифов «от оплаты» и пакетов следующего счёта без оплаты нет, поэтому ушла та, чей счёт не оплачен дольше одного цикла после срока (у пакета — 30 дней);
- отменённая до своего старта не считается ни новой, ни ушедшей;
- закончилась (
ended) — дошла до даты окончания (учебный год). Это не уход; - вернулась (
returned) — новая подписка того, у кого раньше была ушедшая; churn_rate—left_of_start ÷ at_start: из действовавших на первое число (пришедший и ушедший в том же месяце в долю не входит). В идущем месяце — только уже случившееся;attendance_rate— пришёл ÷ (пришёл + пропустил) по отмеченным занятиям,null, если занятия не отмечают;why:no_pay— два периода без оплаты, остальное — причина отмены (no_response,price,left,quality,other).reasons— по всему месяцу,left_list— не больше 100;- подписка на паузе считается действующей: история пауз не хранится.
Удержание и ценность клиента
С тарифа «Мини»; на Free — 403 plan_free.
curl "https://kazpayment.kz/api/v1/metrics/retention?month=2026-10" -H "Authorization: Bearer $KEY"
{
"month": "2026-10",
"cohorts": [
{"month": "2026-06", "size": 4, "after_1": 0.75, "after_3": 0.75, "after_6": null, "after_12": null}
],
"months": [{"month": "2026-10", "partial": false, "nrr": 1.05}],
"ltv": 120000, "lifetime_months": 12, "avg_payment": 10000, "avg_churn": 0.0833
}
cohorts— 24 месяца старта: доля подписок, ещё действующих через 1, 3, 6 и 12 месяцев после своего старта.null— срок ещё не наступил для всей когорты. В идущем месяце — только уже начавшиеся подписки;monthsздесь 14, а не 13: у идущего месяцаnrrпуст, и так у последнего полного остаётся сравнение с годом назад;nrr— удержание выручки год к году: деньги месяца от клиентов, плативших ровно год назад, к их деньгам тогда. Новые клиенты не входят. У идущего месяца —null: неполный месяц против полного дал бы ложный обвал;ltv— оценка ценности подписки:avg_payment × lifetime_months, гдеavg_payment— средний платёж на подписку в месяц,lifetime_months = 1 ÷ avg_churn(не больше 120), за шесть последних полных месяцев.null— оттока или платежей не было: делить не на что.
Магазин и разовые оплаты
curl "https://kazpayment.kz/api/v1/metrics/shop?month=2026-10" -H "Authorization: Bearer $KEY"
Заказы через API и оплаты по QR на товары. Отгрузки и подписки сюда не входят.
{
"month": "2026-10",
"months": [
{"month": "2026-10", "partial": false, "created": 4, "created_paid": 2, "conversion": 0.5,
"paid_count": 2, "sales": 12000, "avg_check": 6000, "buyers": 1, "repeat_buyers": 1,
"repeat_rate": 1, "refunded": 1000, "refund_rate": 0.0833}
],
"top": [{"product_id": "…", "name": "Букет", "count": 1, "sales": 7000}]
}
created— заведено в месяце (у QR — открытий страницы оплаты),created_paid— из них оплачено,conversion— доля;paid_count,sales,avg_check— по дню оплаты;buyers,repeat_buyers— покупатели с телефоном и те из них, кто покупал раньше этого месяца. Заказ без телефона не узнать, он не входит;refunded— возвращено в месяце,refund_rate— к поступлениям месяца;top— товары с QR по выручке месяца, до 10.
Опт и отгрузки
curl "https://kazpayment.kz/api/v1/metrics/wholesale?month=2026-10" -H "Authorization: Bearer $KEY"
{
"month": "2026-10",
"months": [
{"month": "2026-10", "partial": false, "shipments": 2, "shipped": 150000, "collected": 110000,
"billed": 150000, "billed_collected": 110000, "collection_rate": 0.7333, "days_to_pay": 14, "days_after_bill": 4}
],
"debtors": [
{"payer_id": "…", "payer_name": "ТОО Ромашка", "debt": 40000, "shipments": 1,
"oldest_bill_on": "2026-10-06", "days_since_bill": 30}
],
"debt_total": 40000,
"debtors_total": 1
}
- месяц — по дню отгрузки; отменённые отгрузки не считаются;
collected— сколько из отгруженного оплачено на сегодня;billed— из отгруженного со счётом, уже выставленным;collection_rate— оплаченное изbilled(оплачено из него —billed_collected): идущая отсрочка долю не занижает;days_to_pay— среднее от отгрузки до полной оплаты,days_after_bill— от счёта (отгрузка + отсрочка) до оплаты; меньше нуля — заплатили раньше счёта. Считаются только оплаченные отгрузки;debtors— на сегодня, а не на выбранный месяц: только отгрузки, счёт по которым уже выставлен. Больший долг первым, в списке не больше 100, всего —debtors_total.
Недельная сводка
Письмо или сообщение владельцу по понедельникам в 9:00 по поясу бизнеса: деньги
за неделю, просрочка, новые и ушедшие подписки, кого проверить. В Telegram, если
он привязан, иначе на почту. Выключена по умолчанию. Включить можно с тарифа
«Мини» (на Free — 403 plan_free), выключить — всегда.
curl https://kazpayment.kz/api/v1/metrics/digest -H "Authorization: Bearer $KEY"
# → {"enabled":false}
curl -X PUT https://kazpayment.kz/api/v1/metrics/digest \
-H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
-d '{"enabled":true}'
Чек-лист перед боевым запуском
- Ключ и секрет вебхука лежат в переменных окружения, а не в коде.
external_ref— ваш настоящий номер заказа, уникальный и не переиспользуемый.- Повтор запроса после таймаута идёт с тем же телом.
- Подпись вебхука проверяется по сырым байтам до разбора JSON.
event_idдедуплицируется: одно событие закрывает сделку один раз.- Приёмник отвечает 2xx за 10 секунд, тяжёлую работу делает после ответа.
- Есть запасной путь на случай, если вебхук не дошёл: опрос
GET /api/v1/orders/<ref>. - Коды ошибок обрабатываются по
code, а не по тексту. - Проведена одна настоящая оплата на маленькую сумму и возврат по ней.
Безопасность
Ключ интеграции даёт право заводить требования денег от имени бизнеса —
это доступ к деньгам. Храните его как пароль: переменные окружения, не в
репозитории, не в браузерном коде. Ключ работает только с /api/v1 и не даёт
входа в панель.
Секрет вебхука показывается один раз при настройке. Потерян — выпустите
новый повторным PUT /api/v1/webhook (это и есть ротация) и обновите его у
себя: старый перестаёт работать сразу.
Ключ мог утечь — отзовите его в кабинете («Подключения» → «Интеграция» → «Отозвать») и выпустите новый: заведение заказов по старому ключу прекратится немедленно.
Мы со своей стороны не передаём в вебхуке персональных данных клиента: в событии только идентификаторы, суммы и время.
Чего API не обещает
Деньги идут напрямую бизнесу, минуя нас: мы выставляем требование через кассу Kaspi самого бизнеса и читаем его выписку. Мы не платёжный агент и денег не держим.
Оплата зависит от кассы бизнеса. Если его сессия Kaspi отвалилась, выпуск кода вернёт ошибку, пока владелец не войдёт заново. Это его касса, не наша.
Что есть только в кабинете — намеренно. Правило: всё, что бизнес делает в кабинете, доступно и по ключу. Исключения ниже — решение владельца KazPayment, у каждого своя причина:
- создание и правка тарифов — цену услуги решает владелец бизнеса, а не
интеграция; прочитать тарифы можно (
GET /api/v1/plans); - вход в кассу Kaspi — нужен код из SMS на телефон кассира; проверить,
подключена ли касса, можно (
GET /api/v1/kaspi); - сотрудники, их права и вход в кабинет (двухэтапный вход, ключи API) — ключ, утёкший из кода сайта, не должен уметь выдавать доступы;
- расчёты бизнеса с KazPayment — выбор и оплата тарифа, «Оплачено до», счёт заранее. Ключом бизнеса нельзя; приложение платформы делает это за заведённых им продавцов (тариф продавца);
- раздел оператора «Клиенты сейчас» — данные всех клиентов сразу видит только владелец платформы; ключ бизнеса к ним доступа не даёт;
- на какой кассе Kaspi стоит бизнес (общая касса своих проектов, 08.11.2026) — переставляет только оператор платформы: ключ бизнеса, сумевший сменить кассу, пустил бы чужие оплаты через чужую сессию Kaspi;
- разбор расхождений (привязать оплату без счёта к начислению или отметить «не наша оплата») — оплата уже не опознана автоматически, и чья она, решает человек, сверяясь с выпиской Kaspi: ошибка закрыла бы чужой долг.
Версия в пути меняется, когда меняется контракт. Новое необязательное поле в ответе версию не двигает — не полагайтесь на то, что список полей неизменен.