> Источник: https://apipay.kz/invoice-by-phone · apipay.kz > ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay. # Создание счёта по номеру телефона **TL;DR.** Чтобы выставить счёт Kaspi по номеру телефона, достаточно одного запроса `POST https://api.apipay.kz/api/v1/invoices` с заголовком `X-API-Key`: в теле — номер покупателя в формате `8XXXXXXXXXX` и сумма. Покупатель получает уведомление в своём приложении Kaspi и оплачивает в пару касаний, деньги идут напрямую на ваш Kaspi-счёт. Ответ приходит сразу со статусом `processing` — выставление в Kaspi асинхронное, итог принесёт вебхук. Счёт живёт 24 часа. ApiPay — независимый сервис и не аффилирован с АО «Kaspi Bank». Он работает поверх штатной роли «Кассир» вашего собственного приложения Kaspi Pay: счета выставляет ваш код, а не человек за прилавком. ## Как это работает 1. **API-запрос** — ваш сервер отправляет сумму и телефон клиента. 2. **Уведомление в Kaspi** — клиент получает его в приложении Kaspi.kz. 3. **Оплата** — клиент подтверждает одним нажатием. 4. **Вебхук** — ваш сервер получает уведомление об оплате. ## Три способа получить оплату — счёт по номеру один из них Выберите способ до того, как писать код. | Способ | Эндпоинт | Что отдаёт | Срок жизни | Когда выбирать | |---|---|---|---|---| | Счёт по номеру телефона | `POST /invoices` | покупатель получает push в приложении Kaspi. Ссылки для отправки у такого счёта нет — есть вычисляемое поле `kaspi_qr_link` (ссылка/QR по этому счёту; `null` в статусе `processing` и всегда `null` в песочнице) | 24 часа | знаете номер покупателя в формате `8XXXXXXXXXX` | | Оплата по ссылке или QR | `POST /invoices/qr` | `qr_token_url` — **ссылка на оплату (payment link)**: отправьте её покупателю в мессенджер или откройте на его телефоне, сканировать не обязательно. `qr_image_url` — готовый PNG, если QR нужно показать на экране | окно на скан или открытие ссылки задаёт Kaspi (минуты) — точный момент берите из `qr_expires_at`, константу не зашивайте | покупатель здесь и сейчас: в зале у кассы, в чате, на сайте. Подробности — [QR-счёт: TTL и лимиты](https://apipay.kz/guides/qr-schet-ttl-i-limity.md) | | Печатный QR под сделку | `POST /static-qr` | `print_url` — **долгоживущая ссылка на страницу оплаты**, её же кодирует QR-картинка; `short_code` для ручного ввода; `qr_image_url` — готовый PNG | живёт, пока лист не оплачен, не отключён `DELETE /static-qr/{id}` и не наступил заданный вами `expires_at` | оплатить позже: напечатать, вложить в заказ, отправить «на потом». См. [справочник API](https://apipay.kz/apipay-api-docs.md) | Счёт по номеру не требует экрана для показа, работает в разговоре и в чате, приносит покупателю уведомление и идентифицирует его по номеру. ## Что видит покупатель Обычный счёт Kaspi в своём приложении Kaspi. Уведомление приходит обычно в течение минуты; если push потерялся, счёт всё равно ждёт внутри приложения. Оплата — пара касаний, платит покупатель тем, чем привык: Kaspi Gold, Kaspi Red, в рассрочку. Ссылок на сторонние сайты и ввода данных карты нет, деньги идут на ваш Kaspi-счёт. В уведомлении покупатель видит номер вашего кассира — это штатное поведение Kaspi и на оплату не влияет. Kaspi удерживает свою обычную комиссию за приём платежа по вашим условиям Kaspi Pay — она не связана с ApiPay. Покупателю не нужен Kaspi Pay: это приложение для предпринимателей, оно нужно вам. Достаточно обычного приложения Kaspi на его номере. ## Пример запроса и ответа ```http POST https://api.apipay.kz/api/v1/invoices Content-Type: application/json X-API-Key: your_api_key { "amount": 25000, "phone_number": "87071234567", "description": "Заказ #456", "external_order_id": "order_456", "external_order_id_idempotency": "order_456" } ``` Ответ `201 Created` — создание асинхронное: ```json { "id": 123, "amount": "25000.00", "status": "processing", "created_at": "2026-02-12T10:30:00+00:00" } ``` `processing` означает «принято в работу», а не ошибку. **Не пересоздавайте счёт, пока он в `processing`** — получатся два живых счёта, и покупатель может оплатить оба. Передавайте `external_order_id_idempotency`: повтор с тем же значением вернёт `409 duplicate_idempotency_key` с `id` и статусом уже существующего счёта. API-ключ выпускается в кабинете apipay.kz, «Настройки» → «Подключение». Это серверный секрет: в код, исполняемый в браузере, в мобильное приложение и в публичный репозиторий его класть нельзя. ## Сроки и лимиты | Параметр | Значение | |---|---| | Срок жизни счёта | 24 часа, фиксированный — вручную не задаётся | | Формат номера | `8XXXXXXXXXX` — 11 цифр, ведущая 8, без «+7» и пробелов | | Сумма | только целые тенге; дробная даёт `422 amount_must_be_whole_tenge` | | Описание | `description` до 60 символов — Kaspi показывает покупателю только первые 60 | | Лимит запросов | 200 запросов в минуту на API-ключ | Копейки счёт по номеру не принимает. Если они нужны, счёт выставляется через `POST /invoices/qr` — там суммы с тиынами проходят. Порядок выхода в боевой режим: регистрация → анкета «Расскажите о бизнесе» → подключение кассира → боевые счета. **До одобрения анкеты боевых счетов у организации ноль** — первая же попытка даёт `429 kyc_daily_limit_reached`, порог читайте из `meta.limit`. Песочница доступна сразу после регистрации и анкеты не требует; счета в Kaspi из неё не уходят. Дневной лимит счетов, созданных через API, зависит от тарифа: Старт — 10 000 ₸/мес, до 30 счетов в день; Бизнес — 25 000 ₸/мес, до 100; Про — 60 000 ₸/мес, до 300; Про Макс — 90 000 ₸/мес, до 600. Больше 600 в день — договорная цена. Разовое превышение работу не блокирует. При систематическом превышении ограничение включается: счета сверх лимита в течение суток не создаются, а API отвечает `429 tariff_limit_reached` с `Retry-After` и `meta` (`mode`, `limit`, `used`, `reset_at`); расход виден в `GET /users/me` → `daily_usage`. Подписка фиксированная, без процента с оборота. ## Статусы и вебхук Путь счёта: `processing` → `pending` → `paid` / `cancelled` / `expired`; если выставить не удалось — `error`. | Статус | Что значит | |---|---| | `processing` | счёт создаётся, Kaspi ещё вызывается — вебхука нет | | `pending` | счёт в Kaspi, ждёт оплаты | | `paid` | оплачен, деньги на вашем Kaspi-счёте | | `cancelled` | отменён вами или покупателем | | `expired` | истекли 24 часа | | `error` | не удалось создать в Kaspi (терминальный) | | `partially_refunded` | сделан частичный возврат | Об оплате узнаёте вебхуком `invoice.status_changed`: при смене статуса ApiPay сам делает POST на ваш HTTPS-адрес, оплату обычно видно за 10–30 секунд, в отдельных случаях — до 10 минут; деньги при этом уже у вас, задержка только в уведомлении. Адрес и секрет задаются в кабинете, подпись приходит в заголовке `X-Webhook-Signature: sha256=` — это HMAC-SHA256 от **сырого** тела запроса, не парсите JSON до проверки подписи. Опрашивать статус в цикле не нужно. Дедуплицируйте по паре (`invoice.id`, `invoice.status`). Заложите в обработчик законные «странные» переходы: `cancelled → paid` и `expired → paid` (покупатель успел оплатить на границе), `error → pending` (счёт ожил при сверке с Kaspi). Статуса `refunded` у счёта не существует — после полного возврата остаётся `paid` с признаком `is_fully_refunded`. Отменить счёт по номеру можно: `POST /invoices/{id}/cancel` для `pending`/`processing`. В боевом режиме ответ `202` и статус `cancelling` — после него отменённым счёт не считайте, реальный исход принесёт вебхук или `GET /invoices/{id}`. ## Ошибки Причину падения в `error` несёт машиночитаемый `error_code` — он же в вебхуке и в `GET /invoices/{id}`. | `error_code` | Причина | Что делать | |---|---|---| | `client_not_found` | номер не зарегистрирован в Kaspi | уточнить номер; счёт на этот номер невозможен, покупатель ничего не увидит | | `session_transient` | проблема с авторизацией кассира Kaspi | создать счёт заново; если повторяется — переподключить кассира | | `kaspi_throttled` | Kaspi ограничил частоту запросов кассира | подождать 2–3 минуты, снизить темп и создать новый счёт | | `network_unavailable` | Kaspi временно недоступен | повторить через 1–2 минуты | | `unknown_error` | попытки исчерпаны без диагноза | написать в поддержку с `id` счёта | Статус `error` терминален: «повторить» означает создать новый счёт. Полный каталог кодов — [errors.md](https://apipay.kz/errors.md). ## Частые вопросы **Как выставить счёт Kaspi по номеру телефона через API?** Один запрос `POST https://api.apipay.kz/api/v1/invoices` с заголовком `X-API-Key`: в теле — номер покупателя в формате `8XXXXXXXXXX` и сумма. Ответ приходит сразу со статусом `processing`, итог принесёт вебхук. **Сколько времени у покупателя на оплату?** 24 часа, срок фиксированный. Не оплатил — статус «Истек», выставляете новый. **Нужен ли покупателю Kaspi Pay?** Нет. Kaspi Pay — приложение для предпринимателей, оно нужно вам. Покупателю достаточно обычного приложения Kaspi. **Можно ли выставить счёт с копейками?** Нет, только целые тенге. Если нужны копейки — `POST /invoices/qr` принимает суммы с тиынами. **Где это применяют?** Доставка (курьер звонит и называет сумму), телефонные продажи, услуги на выезде, интернет-магазины без редиректов, счета на продление, продажи в Instagram, WhatsApp и Telegram. ## Куда дальше - [Как создать счёт Kaspi по номеру телефона](https://apipay.kz/guides/kak-sozdat-schet-kaspi-po-nomeru.md) — пошагово, с идемпотентностью и разбором ошибок - [Что видит покупатель](https://apipay.kz/guides/chto-vidit-pokupatel.md) - [Жизненный цикл счёта](https://apipay.kz/guides/zhiznennyy-tsikl-scheta.md) - [Как настроить вебхуки ApiPay](https://apipay.kz/guides/nastroyka-webhookov-apipay.md) - [API-ключ и вебхук-секрет](https://apipay.kz/guides/api-klyuch-i-webhook-secret.md) · [Песочница и рабочий режим](https://apipay.kz/guides/pesochnitsa-i-rabochiy-rezhim.md) · [Анкета о бизнесе и лимит](https://apipay.kz/guides/anketa-o-biznese-i-limit.md) - [Как подключить Kaspi Pay к сайту](https://apipay.kz/kaspi-pay-integration.md) - [Справочник REST API](https://apipay.kz/apipay-api-docs.md) · [Каталог ошибок](https://apipay.kz/errors.md) · [Обзор сайта](https://apipay.kz/index.md) --- ApiPay — независимый сервис и не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки их правообладателя.