Гайд

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

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 — для человека.