Счета Kaspi через API

    4 мин чтения
    ·
    5 просмотров
    ·
    Обновлено 18.11.2026

    Счета 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
    ПараметрТипОбязательныйОписание
    phonestring✅Номер клиента в Kaspi, Казахстан: +77011234567, 87011234567 или 7011234567
    amountnumber✅Сумма в тенге, больше 0 и не больше 5 000 000
    commentstringНетКомментарий к счёту до 200 символов, например номер заказа и товар. Клиент видит его в Kaspi
    externalIdstringНетНомер заказа в вашей системе, до 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Причина
    400bad_phone, bad_amount, bad_external_idНеверный номер, сумма или externalId
    402no_tariffНет действующего тарифа Kaspi Pay и пробный период закончился. Оплатите тариф: Коннекторы → Kaspi Pay
    402plan_limitЛимит оплат тарифа «Старт» в этом месяце исчерпан
    403kaspi_not_enabledСчета Kaspi для этого ключа не включены
    403kaspi_auto_stoppedСчета ключа остановлены автоматически из-за массовых отказов, включает поддержка
    404not_foundСчёт не найден среди счетов вашего ключа
    409not_connected, needs_reauthКассир не подключён или его нужно подключить заново в кабинете
    409not_cancellableСчёт уже оплачен или закрыт
    429rate_limit_minute, rate_limit_dayПревышен лимит счетов ключа
    429kassa_day_limitКассир выставил 300 счетов за сутки, повторите завтра
    502kaspi_errorKaspi не принял запрос, повторите позже