Документация Sezgir Pay

Как это устроено#

В кабинете вы заводите сервисы — интернет-магазин, бота, POS-терминал, мобильное приложение. У каждого сервиса свои API-ключи, вебхуки и платежи; сервисы не видят данные друг друга.

Каждый сервис привязан в кабинете к одному из подключённых кассиров Kaspi (Сервис → Настройки → «Кассир Kaspi»). Боевые платежи сервиса проводятся через этого кассира, и деньги зачисляются прямо на его счёт Kaspi — Sezgir Pay не хранит и не пересылает средства. Если сменить кассира, новые платежи пойдут на новый счёт, а уже созданные платежи и возвраты по ним останутся за прежним. Для API при этом ничего не меняется — те же ключи, запросы и вебхуки.

Быстрый старт#

Ниже — полный путь от ключа до оплаченного заказа в тестовом режиме. Деньги при этом не списываются.

1. Получите тестовый API-ключ

   Откройте кабинет → Сервисы → ваш сервис → API-ключи и создайте ключ в тестовом режиме. Он начинается с sk_test_ и показывается один раз — сохраните его в переменной окружения:

   Терминал

   Копировать

   export SEZGIR_API_KEY="sk_test_…"

2. Создайте платёж

   Платёжная ссылка — самый простой способ: вам не нужно рисовать QR, страницу оплаты Sezgir Pay берёт на себя. Сумма указывается в целых тенге.

   curlNode.jsPythonPHP

   Копировать

   curl https://pay.sezgir.com/api/v1/payments \
     -H "Authorization: Bearer $SEZGIR_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 9f1c2a4e-7b3d-4e8a-a1f0-5c6d7e8f9a0b" \
     -d '{
       "type": "link",
       "amount": 15000,
       "description": "Заказ №1042",
       "external_id": "order_1042",
       "metadata": { "order_id": 1042, "channel": "web" }
     }'

   В ответ придёт объект платежа в статусе pending:

   Ответ · 201 Created

   Копировать

   {
     "id": "pay_2Nf8kQ1xYbV7cR4tLm9Pa3Ws",
     "object": "payment",
     "livemode": false,
     "project_id": "prj_7HcTq2LwZ9mRk4VbN1sXe8Dy",
     "type": "link",
     "status": "pending",
     "amount": 15000,
     "amount_refunded": 0,
     "currency": "KZT",
     "description": "Заказ №1042",
     "phone": null,
     "external_id": "order_1042",
     "metadata": {
       "order_id": 1042,
       "channel": "web"
     },
     "checkout_url": "https://pay.sezgir.com/pay/pay_2Nf8kQ1xYbV7cR4tLm9Pa3Ws",
     "provider": {
       "name": "test",
       "operation_id": null,
       "kind": null,
       "status": null,
       "qr_url": null,
       "qr_expires_at": null
     },
     "failure_reason": null,
     "requires_review": false,
     "expires_at": "2026-11-01T09:14:03.512Z",
     "paid_at": null,
     "canceled_at": null,
     "created_at": "2026-10-25T09:14:03.512Z"
   }

3. Отправьте покупателя на страницу оплаты

   Перенаправьте покупателя на checkout_url или отправьте ссылку в мессенджер. На странице он увидит название вашего сервиса, сумму и кнопку оплаты через Kaspi.kz. В тестовом режиме там же есть кнопки «Оплатить» и «Отклонить» — нажмите «Оплатить».

4. Получите вебхук и выполните заказ

   Добавьте URL вебхука в кабинете (Сервис → Вебхуки). После оплаты на него придёт событие payment.succeeded с объектом платежа. Проверьте подпись, найдите заказ по external_id или metadata и отметьте его оплаченным. Подробно — в разделе Вебхуки.

5. Перейдите в боевой режим

   Убедитесь, что к сервису привязан подключённый кассир Kaspi, создайте ключ sk_live_ и боевой вебхук с адресом https://. Код менять не нужно — режим определяется ключом.

Основы API#

Что дальше#

Чек-лист надёжной интеграции:

• передавайте Idempotency-Key при создании платежей и возвратов и повторяйте запрос с тем же ключом при сетевой ошибке;
• подтверждайте заказы по вебхуку payment.succeeded, а не по возврату покупателя со страницы оплаты;
• будьте готовы к payment.succeeded в любой момент — даже после expired или canceled (см. поздняя оплата);
• обрабатывайте ошибки по полям type и code, а не по тексту сообщения.