Счета Kaspi из вашей системы
Ваша CRM или сайт выставляет клиенту счёт Kaspi на любую сумму по номеру телефона. Клиент получает счёт в приложении Kaspi и оплачивает его. Когда оплата прошла, на ваш вебхук приходит событие kaspi_invoice_paid: по нему вы закрываете заказ и, если нужно, пишете клиенту через POST /v1/messages/send.
Что нужно до начала
- Кассир Kaspi Pay подключён в кабинете: Настройки → Интеграции → Kaspi Pay. Нужен отдельный номер с ролью «Кассир».
- Действует тариф Kaspi Pay: «Старт» (до 150 оплат в месяц на кассу) или «Безлимит». Оплатить его можно в кабинете: Коннекторы → Kaspi Pay. После первого подключения кассира даётся пробный период 7 дней. Если у вас действует CRM WazzaBee (пробная или оплаченная), счета бесплатны.
- Счета Kaspi включены для вашего API-ключа. Их включает поддержка WazzaBee по вашей просьбе, у остальных ключей методы отвечают ошибкой 403.
- Вебхук ключа настроен через PATCH /v1/webhooks. События Kaspi приходят на него без отдельной подписки.
Защита от лишних счетов
- Не больше 5 счетов в минуту и 100 в сутки на один ключ. Если вам нужно больше, напишите в поддержку.
- Повторный запрос с тем же
externalIdне создаёт второй счёт, а возвращает первый с"duplicate": true. - Если на тот же номер и ту же сумму за последние 30 минут уже есть неоплаченный счёт, новый не создаётся, в ответе приходит существующий.
- Не больше 300 счетов в сутки на одного кассира со всех путей вместе: API, меню-бот и сделки CRM.
- Если за сутки клиенты отклонили или не оплатили 10 и больше счетов ключа и это больше половины закрытых, счета Kaspi для ключа останавливаются автоматически (ошибка
kaspi_auto_stopped). Включить их снова можно через поддержку.
POST /v1/kaspi/invoices
Выставить счёт.
POST https://api.wazzabee.com/api-gateway/v1/kaspi/invoices
Authorization: Bearer ВАШ_API_КЛЮЧ
Content-Type: application/json
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
phone | string | ✅ | Номер клиента в Kaspi, Казахстан: +77011234567, 87011234567 или 7011234567 |
amount | number | ✅ | Сумма в тенге, больше 0 и не больше 5 000 000 |
comment | string | Нет | Комментарий к счёту до 200 символов, например номер заказа и товар. Клиент видит его в Kaspi |
externalId | string | Нет | Номер заказа в вашей системе, до 100 символов. Защищает от двойного счёта при повторе запроса |
curl -X POST "https://api.wazzabee.com/api-gateway/v1/kaspi/invoices" \
-H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{"phone": "+77011234567", "amount": 15000, "comment": "Заказ 1024, чехол", "externalId": "1024"}'
Ответ 201 (новый счёт) или 200 (повтор, "duplicate": true):
{
"success": true,
"duplicate": false,
"invoice": {
"invoiceId": "uuid",
"externalId": "1024",
"phone": "+77011234567",
"amount": 15000,
"comment": "Заказ 1024, чехол",
"status": "pending",
"createdAt": "2026-11-17T14:00:00.000Z",
"paidAt": null
}
}
Статусы счёта: pending (ждёт оплаты), paid (оплачен), expired (истёк), cancelled (отменён), unknown (Kaspi не дал ответа за 3 дня).
GET /v1/kaspi/invoices/{invoiceId}
Счёт по его invoiceId. Ответ: {"success": true, "invoice": {...}}. Статус обновляется раз в минуту.
GET /v1/kaspi/invoices
Счета вашего ключа, новые сверху. Параметры строки запроса: from и to (дата ISO 8601), status (pending, paid, expired, cancelled, unknown), limit (1–200, по умолчанию 50).
GET https://api.wazzabee.com/api-gateway/v1/kaspi/invoices?from=2026-11-01T00:00:00Z&status=paid
POST /v1/kaspi/invoices/{invoiceId}/cancel
Отменить неоплаченный счёт. Ответ: {"success": true, "invoice": {..., "status": "cancelled"}}. Вебхук на свою отмену не приходит, результат сразу в ответе.
События в вебхук
| Событие | Когда |
|---|---|
kaspi_invoice_paid | Клиент оплатил счёт |
kaspi_invoice_expired | Срок оплаты счёта истёк |
kaspi_invoice_cancelled | Клиент отклонил счёт или его отменили в Kaspi |
{
"event": "kaspi_invoice_paid",
"invoice": {
"invoiceId": "uuid",
"externalId": "1024",
"phone": "+77011234567",
"amount": 15000,
"comment": "Заказ 1024, чехол",
"status": "paid",
"createdAt": "2026-11-17T14:00:00.000Z",
"paidAt": "2026-11-17T14:03:10.000Z"
},
"timestamp": "2026-11-17T14:03:40.000Z"
}
Событие приходит в течение минуты после изменения статуса, с подписью и повторами, как остальные вебхуки WazzaBee. Сверить статус можно через GET /v1/kaspi/invoices/{invoiceId}.
Возможные ошибки
| Код | error | Причина |
|---|---|---|
400 | bad_phone, bad_amount, bad_external_id | Неверный номер, сумма или externalId |
402 | no_tariff | Нет действующего тарифа Kaspi Pay и пробный период закончился. Оплатите тариф: Коннекторы → Kaspi Pay |
402 | plan_limit | Лимит оплат тарифа «Старт» в этом месяце исчерпан |
403 | kaspi_not_enabled | Счета Kaspi для этого ключа не включены |
403 | kaspi_auto_stopped | Счета ключа остановлены автоматически из-за массовых отказов, включает поддержка |
404 | not_found | Счёт не найден среди счетов вашего ключа |
409 | not_connected, needs_reauth | Кассир не подключён или его нужно подключить заново в кабинете |
409 | not_cancellable | Счёт уже оплачен или закрыт |
429 | rate_limit_minute, rate_limit_day | Превышен лимит счетов ключа |
429 | kassa_day_limit | Кассир выставил 300 счетов за сутки, повторите завтра |
502 | kaspi_error | Kaspi не принял запрос, повторите позже |
