Действующая редакция контракта. Обновлено: 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 повторять бесполезно: ответ не изменится.

Частично оплаченный заказ

Что делать, если часть денег уже пришла, решает бизнес в кабинете: «Подключения» → «Интеграция» → «Отмена частично оплаченного заказа».

Что нельзя забрать назад: 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 («Возврат отклонен») без объяснения причины. Две причины, которые мы видели вживую:

Возраст платежа сам по себе помехой не оказался: двухсуточная оплата вернулась без вопросов. Отказ -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 работает целиком, но денег нет:

Программной ручки «оплатить за клиента» в API нет намеренно: в бою такой не бывает, и код, написанный вокруг неё, пришлось бы переписывать. Кнопки на странице оплаты — другое дело: в бою там тоже стоит человек.

Исключение — коды подтверждения по SMS: они настоящие и в песочнице недоступны (SMS стоят денег, а баланса у песочницы нет).

Что стоит проверить в песочнице до боевого запуска:

Абонементы: клиент и подписка

Заказ — это разовая оплата. Если ваш бизнес продаёт абонементы (школа, зал, курсы), нужно другое: завести человека, подписать его на тариф, и дальше начисления с напоминаниями пойдут сами — как из кабинета, только программно.

Типичный путь интеграции с вашей 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"}

Повтор с тем же клиентом и тем же тарифом вернёт действующую подписку (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:

Настройки бизнеса

То же, что владелец настраивает в кабинете, доступно по ключу.

Если клиент не оплатил подписку — общее правило тарифов («Тарифы» в кабинете; оно же видно в «Напоминаниях»):

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:

Настройки бизнеса

То же, что владелец настраивает в кабинете, доступно по ключу.

Если клиент не оплатил подписку («Напоминания» в кабинете):

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 Отправка кодов не подключена на стороне сервиса

Пределы и почему они такие

Имя отправителя в 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 Месяц ещё идёт

Что считается:

Клиенты: приток и отток

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"}
  ]
}

Удержание и ценность клиента

С тарифа «Мини»; на 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
}

Магазин и разовые оплаты

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}]
}

Опт и отгрузки

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
}

Недельная сводка

Письмо или сообщение владельцу по понедельникам в 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}'

Чек-лист перед боевым запуском

  1. Ключ и секрет вебхука лежат в переменных окружения, а не в коде.
  2. external_ref — ваш настоящий номер заказа, уникальный и не переиспользуемый.
  3. Повтор запроса после таймаута идёт с тем же телом.
  4. Подпись вебхука проверяется по сырым байтам до разбора JSON.
  5. event_id дедуплицируется: одно событие закрывает сделку один раз.
  6. Приёмник отвечает 2xx за 10 секунд, тяжёлую работу делает после ответа.
  7. Есть запасной путь на случай, если вебхук не дошёл: опрос GET /api/v1/orders/<ref>.
  8. Коды ошибок обрабатываются по code, а не по тексту.
  9. Проведена одна настоящая оплата на маленькую сумму и возврат по ней.

Безопасность

Ключ интеграции даёт право заводить требования денег от имени бизнеса — это доступ к деньгам. Храните его как пароль: переменные окружения, не в репозитории, не в браузерном коде. Ключ работает только с /api/v1 и не даёт входа в панель.

Секрет вебхука показывается один раз при настройке. Потерян — выпустите новый повторным PUT /api/v1/webhook (это и есть ротация) и обновите его у себя: старый перестаёт работать сразу.

Ключ мог утечь — отзовите его в кабинете («Подключения» → «Интеграция» → «Отозвать») и выпустите новый: заведение заказов по старому ключу прекратится немедленно.

Мы со своей стороны не передаём в вебхуке персональных данных клиента: в событии только идентификаторы, суммы и время.

Чего API не обещает

Деньги идут напрямую бизнесу, минуя нас: мы выставляем требование через кассу Kaspi самого бизнеса и читаем его выписку. Мы не платёжный агент и денег не держим.

Оплата зависит от кассы бизнеса. Если его сессия Kaspi отвалилась, выпуск кода вернёт ошибку, пока владелец не войдёт заново. Это его касса, не наша.

Что есть только в кабинете — намеренно. Правило: всё, что бизнес делает в кабинете, доступно и по ключу. Исключения ниже — решение владельца KazPayment, у каждого своя причина:

Версия в пути меняется, когда меняется контракт. Новое необязательное поле в ответе версию не двигает — не полагайтесь на то, что список полей неизменен.