Как выставить удалённый счёт вручную
- Откройте приложение Kaspi Pay на телефоне под учётной записью, у которой есть право выставлять счета.
- Перейдите в раздел удалённых счетов.
- Введите номер телефона покупателя и сумму, при необходимости — короткое описание.
- Подтвердите выставление. Счёт уходит покупателю в его приложение Kaspi.
- Дождитесь подтверждения. Когда покупатель оплатит, счёт в приложении Kaspi Pay сменит статус на оплаченный.
Названия разделов и кнопок в приложении задаёт Kaspi и время от времени меняет — актуальную инструкцию по удалённой оплате смотрите в справке Kaspi. Права, которые есть у сотрудника с ролью «Кассир», Kaspi описывает отдельно: «Какие права у кассира».
Что видит покупатель
Покупатель получает уведомление в своём приложении Kaspi: продавец, сумма, описание и кнопка оплаты. Карту вводить не нужно — оплата проходит внутри Kaspi, деньги идут напрямую на ваш Kaspi-счёт. Подробный разбор экрана покупателя — «Что видит покупатель».
Когда счетов больше, чем можно выставить руками
Ручное выставление упирается в человека: пока кто-то не наберёт номер и сумму на телефоне, счёт не появится. Пора автоматизировать, если:
- счетов в день десятки и набирать их руками стало долго;
- счёт должен уходить сам — в момент оформления заказа на сайте, сделки в CRM, документа в 1С;
- другая система ждёт факт оплаты, чтобы отгрузить товар, открыть доступ или закрыть заказ.
Что делает ApiPay. Ваша система отправляет один запрос:
curl -X POST https://api.apipay.kz/api/v1/invoices \
-H "X-API-Key: ВАШ_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "87001234567",
"amount": 5000,
"description": "Оплата заказа №123",
"external_order_id": "order-123",
"external_order_id_idempotency": "order-123"
}'
Ответ 201 приходит сразу со статусом processing — счёт принят в работу. Дальше:
- об оплате сообщает вебхук
invoice.status_changedсо статусомpaid— ваш сервер узнаёт о ней сам, без опроса; - проверить состояние счёта в любой момент можно запросом
GET /api/v1/invoices/{id}; - дубль защищён ключом идемпотентности: повтор с тем же
external_order_id_idempotency, пока прежний счёт жив, отвечает409. Если прежний счёт ужеexpired,cancelledилиerror, тот же ключ создаёт новый счёт — это штатное перевыставление неоплаченного заказа.
Две вещи, о которых стоит знать до первого боевого счёта:
- Новая организация работает в песочнице. Счета в Kaspi не уходят, покупателю ничего не приходит. Для реальных оплат включите рабочий режим в настройках — «Песочница и рабочий режим».
processing— это не «зависло». Пока счёт в этом статусе, не создавайте его заново: получатся два живых счёта, и покупатель может оплатить оба. Если выставить не удалось, счёт уходит вerrorс причиной — самый частый случайclient_not_found: номер не зарегистрирован в Kaspi. Разбор статусов — «Жизненный цикл счёта».
Сумма — только целые тенге, описание — до 60 символов: Kaspi показывает покупателю первые 60. Счёт живёт 24 часа. Пошаговый разбор запроса — «Как создать счёт Kaspi по номеру телефона».
Это тот же Kaspi Pay, та же ваша организация и тот же кабинет Kaspi: ApiPay выставляет счета через штатную роль «Кассир», деньги приходят напрямую на ваш Kaspi-счёт. Переезжать никуда не нужно: ручное выставление в приложении продолжает работать. Одно условие — ApiPay подключается отдельным номером сотрудника с ролью «Кассир», и под этим номером входить в приложение Kaspi Pay нельзя, иначе привязка разорвётся. Своим обычным номером вы выставляете счета руками как раньше — «Требования к номеру кассира».
ApiPay берёт только фиксированную подписку, процента с платежей нет. Комиссию за приём платежа удерживает Kaspi по условиям продавца — к ApiPay она не относится.
Что почитать дальше: страница продукта «Счёт по номеру телефона», полная спецификация — apipay.kz/docs. Код писать самому не обязательно: дайте своему ИИ-агенту страницу apipay.kz/for-ai, там собран план подключения и справочник фактов.
Руками или через ApiPay: что меняется
| Вручную в Kaspi Pay | Через ApiPay | |
|---|---|---|
| Кто выставляет счёт | Человек с телефоном в руках | Ваша система: сайт, CRM, бот, 1С |
| Сколько времени на счёт | Минута на каждый: открыть приложение, набрать номер и сумму | Один запрос, ответ приходит сразу |
| Что со статусом | Смотрите глазами в приложении | Вебхук invoice.status_changed со статусом paid; при необходимости GET /invoices/{id} |
| Что при ошибке | Замечает и повторяет человек | Код отказа приходит в ответе; повтор на тот же заказ защищён external_order_id_idempotency |
| Кому подходит | Единичные счета, продавец у телефона | Поток счетов и передача оплат в другую систему |
Одно другому не мешает: организация может выставлять счета и руками в приложении, и через API.
Частые вопросы
Что такое удалённый счёт в Kaspi Pay?
Это счёт покупателю по номеру его телефона: счёт приходит человеку в его приложение Kaspi, он открывает уведомление и подтверждает оплату. Встречаться, показывать QR и вводить карту не нужно — достаточно знать номер. Руками такой счёт выставляют в приложении Kaspi Pay, автоматически — запросом POST /api/v1/invoices в ApiPay.
Сколько ждёт удалённый счёт, если покупатель не оплатил?
Счёт по номеру телефона живёт 24 часа, после чего уходит в статус expired. Продлить срок нельзя — выставьте новый счёт. Отменить неоплаченный счёт можно раньше — POST /api/v1/invoices/{id}/cancel. В рабочем режиме отмена асинхронная: приходит 202 и статус cancelling, отменённым счёт после этого не считайте. Исходов три: вебхук cancelled; вебхук error с invoice_already_paid; либо тихий возврат в pending, если покупатель успел оплатить — реальный статус тогда принесёт GET /api/v1/invoices/{id}.
Как дать покупателю ссылку на оплату Kaspi?
У счёта по номеру телефона ссылки нет — покупателю приходит уведомление в приложении. Если нужна именно ссылка, которую можно отправить в WhatsApp или Telegram, ссылок две: qr_token_url из POST /api/v1/invoices/qr — для оплаты «прямо сейчас», и print_url из POST /api/v1/static-qr — долгоживущая ссылка печатного листа под сделку, для оплаты «потом». Разбор обоих вариантов — «Оплата Kaspi по ссылке».
Можно ли выставлять удалённые счета автоматически из CRM или с сайта?
Да. Ваша система отправляет POST /api/v1/invoices с номером покупателя и суммой, а факт оплаты получает вебхуком invoice.status_changed со статусом paid. Kaspi Pay, организация и кабинет Kaspi остаются вашими прежними — см. Счёт по номеру телефона и apipay.kz/docs.