Kaspi Pay API: запрос и статус оплаты

01Перед первым запросом

Сохраните получателя, подключённый номер и одобренный шаблон в «Оплаты Kaspi → Настройки». Для создания нужен API-ключ с payments:write, для чтения — payments:read. Активная подписка WAIX API или пробный доступ должны разрешать отправку с выбранного номера.

02Создать оплату

POST https://waix.kz/api/v1/payments/kaspi. Передайте amount — сумму целыми тенге, phone — телефон клиента и необязательный order_number. Сохраните один Idempotency-Key вместе с заказом и повторяйте запрос с ним при сетевой ошибке. Новый ключ означает новый запрос оплаты.

curl https://waix.kz/api/v1/payments/kaspi \
  -H "Authorization: Bearer $WAIX_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: kaspi-order-123-v1' \
  -d '{"amount":12500,"order_number":"123","phone":"+77071234567"}'

Ответ data содержит id, order_number, phone, amount, currency, status, delivery_status, payment_url, widget_url и expires_at. Успешное создание означает, что запрос сохранён. По умолчанию сообщение отправляется сразу. Для виджета сайта передайте delivery="on_open": инструкция уйдёт после перехода покупателя к оплате. Само создание запроса не означает, что клиент уже оплатил или получил сообщение.

03Проверить или отменить

GET /api/v1/payments/kaspi/{id} возвращает текущий статус. GET /api/v1/payments/kaspi — список: status=all|waiting|paid|expired|cancelled, q — поиск по заказу или телефону, offset — смещение. По 50 записей, has_more указывает на следующую страницу.

POST /api/v1/payments/kaspi/{id}/cancel закрывает неоплаченный запрос. POST /api/v1/payments/kaspi/{id}/retry повторяет подготовку сообщения, если оно ещё не было поставлено в очередь WhatsApp. Уже отправленный запрос с тем же ключом повторно не отправляется.

04Webhook payment.paid

Включите событие на HTTPS-адресе компании. Проверяйте X-Waix-Signature по документации вебхуков; сохраняйте ID события и ID оплаты для обработки повторных доставок.

{
  "id": "EVENT_UUID",
  "type": "payment.paid",
  "data": {
    "id": "PAYMENT_UUID",
    "order_number": "123",
    "phone": "+77071234567",
    "amount": 12500,
    "currency": "KZT",
    "status": "paid",
    "verification_source": "customer_receipt",
    "receipt_id": "RECEIPT_UUID"
  }
}

verification_source=customer_receipt означает подтверждение по чеку покупателя. Это не банковский callback. payment.needs_review сообщает receipt_id, phone и reason; такие события требуют проверки сотрудником.

05Ошибки

401 — проверьте API-ключ; 403 — права ключа или роль; 402 — доступ к отправке по тарифу; 409 — выключенные настройки, несовместимый повтор Idempotency-Key или закрытая оплата; 429 — слишком много запросов. Точный текст ошибки отображается в ответе. После сетевой ошибки повторяйте создание с исходным ключом.