Как создать счёт Kaspi по номеру телефона через API?

Три шага: запрос → ответ → покупатель платит

Шаг 1. Отправьте запрос

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

Номер — 11 цифр, начинается с 8: 8XXXXXXXXXX. API-ключ берётся в кабинете apipay.kz (Настройки → «Подключение»); полный ключ показывается только один раз при создании — подробнее в статье «API-ключ и вебхук-секрет».

Шаг 2. Получите ответ 201 со статусом processing

{
  "id": 1,
  "amount": "5000.00",
  "status": "processing",
  "phone": "77001234567",
  "created_at": "2026-07-02T10:25:00+06:00"
}

processing означает «принято в работу»: выставление счёта в Kaspi происходит асинхронно, в фоне. Ничего опрашивать в цикле не нужно — итоговый статус придёт вебхуком (настройка — «Как настроить вебхуки ApiPay»). Для отладки текущее состояние можно посмотреть запросом GET /invoices/{id} — там же видны поля last_kaspi_error_code и last_kaspi_error_message, если Kaspi отвечал ошибкой.

Шаг 3. Что видит покупатель

Покупателю приходит push-уведомление в приложении Kaspi: счёт с вашим описанием и суммой, кнопка «Оплатить». Деньги идут напрямую на ваш Kaspi-счёт.

Какие статусы проходит счёт?

Путь счёта: processing → pending → paid / cancelled / expired; если выставить не удалось — error. Вебхуки приходят на переходы в pending, paid, cancelled, expired, error, partially_refunded; на технические processing и cancelling вебхуков не бывает.

Не пересоздавайте счёт, пока он в processing: получатся два живых счёта, и покупатель может оплатить оба. Бывают законные «странные» переходы — cancelled → paid, expired → paid, error → pending, — их надо заложить в обработчик. Что означает каждый статус и как обрабатывать поздний paid — «Жизненный цикл счёта».

Как не выставить два счёта за один заказ?

Передавайте external_order_id_idempotency (до 191 символа, уникален в пределах организации — удобно класть туда ID заказа). Повторный запрос с тем же значением вернёт 409 duplicate_idempotency_key с invoice_id и status уже существующего счёта — дубль не создастся, даже при гонке двух параллельных запросов.

Исключение: если прежний счёт уже мёртв (expired, cancelled, error), повторный запрос с тем же ключом создаст новый счёт — это штатное перевыставление неоплаченного заказа. Для живых статусов (processing, pending, paid, partially_refunded) всегда будет 409.

Почему счёт ушёл в error?

В вебхуке и в GET /invoices/{id} будет машиночитаемый error_code. Самые частые:

Важно: статус error терминален — по такому счёту сервис больше ничего не сделает. «Повторить» = создать новый счёт.

Вопросы и ответы