Гайд

Как принимать оплату через Kaspi из кода

Редакция AgentPay·6 июня 2026 г.·2 мин чтения

Чтобы принимать оплату через Kaspi программно, нужен посредник, который автоматизирует кассира Kaspi Pay. AgentPay даёт для этого REST API и CLI: подключаете кассира, выставляете счёт одним запросом, получаете событие об оплате вебхуком. Ниже — рабочие примеры.

Шаг 1. Подключите кассира

В приложении Kaspi Pay создайте кассира (раздел «Сотрудники» → «Добавить кассира») на рабочий номер. Затем заведите аккаунт в AgentPay, введите этот номер и подтвердите SMS-кодом из Kaspi. Это занимает около 5 минут и не требует документов.

Шаг 2. Создайте API-ключ

В настройках создайте ключ. Для разработки используйте sk_test_*, для боевых платежей — sk_live_*. Ключ показывается один раз — храните его в .env или secret manager.

Шаг 3. Выставите счёт

Через REST API:

curl -X POST https://agentpay.kz/api/v1/invoices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"client_phone":"77001234567","amount_kzt":5000,"comment":"Pro-подписка"}'

Или через SDK @kaspi-pay/sdk:

import { charge } from '@kaspi-pay/sdk'

const invoice = await charge('77001234567', 5000, 'Pro-подписка')
console.log(invoice.pay_link_url) // ссылка на оплату для клиента

Или одной командой CLI:

agentpay invoices create --phone 77001234567 --amount 5000 --comment "Pro-подписка"

Шаг 4. Узнайте, что счёт оплачен

Не опрашивайте статус в цикле. Подключите вебхук — AgentPay пришлёт событие invoice.paid, как только клиент оплатит. Для локальной разработки используйте agentpay listen, чтобы получать события без публичного URL:

agentpay listen --forward-to http://localhost:3000/webhooks/agentpay

Каждый POST, создающий ресурс, требует Idempotency-Key. Генерируйте UUID на каждую логическую операцию, а не на каждый повтор запроса — повтор с тем же ключом вернёт закешированный ответ.

Лимиты и ошибки

Лимит по умолчанию — 60 запросов в минуту на ключ (заголовки X-RateLimit-*). Ошибки всегда в одной форме: { "error": { "type", "message" } }, где type стабильный (например, no_active_cashier, rate_limited), а message — для человека.