Документация
Кабинет
Начало работы

Тестовый режим

Тестовый режим повторяет боевой API один в один, но ничего не отправляет в Kaspi и не двигает деньги. Результат оплаты вы задаёте сами.

Как устроен

  • Режим определяется ключом: все запросы с ключом sk_test_ работают с тестовыми данными. Код интеграции одинаков для обоих режимов.
  • Тестовые платежи имеют livemode: false и provider.name: "test". Kaspi о них не знает, кассир для них не нужен.
  • Вебхуки тестовых событий уходят только на тестовые адреса вебхуков. Для тестового адреса допускается http://.
  • Тестовые и боевые данные не пересекаются ни в API, ни в выгрузках: переключатель режима в кабинете показывает либо одни, либо другие.

Симуляция оплаты

Тестовый платёж остаётся в статусе pending, пока вы не сымитируете ответ покупателя. Это можно сделать двумя способами:

  1. В кабинете. Откройте платёж в разделе Платежи — для тестового платежа в статусе pending там есть кнопки «Оплатить» и «Отклонить».
  2. На странице оплаты. Откройте checkout_url — внизу страницы есть блок «Тестовый режим: ответ покупателя» с теми же кнопками. Так удобно проверять весь путь покупателя, включая возврат на ваш сайт по вебхуку.

После симуляции сразу появляются события (payment.succeeded или payment.failed) и уходят вебхуки — как в боевом режиме.

curl
curl "https://pay.sezgir.com/api/v1/payments" \
  -H "Authorization: Bearer $SEZGIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "qr", "amount": 300 }'
Ответ · 201 Created (фрагмент)
{
  "id": "pay_6Jk2Lm9Nq4Rs7Tv1Wx3Yz8Ab",
  "livemode": false,
  "type": "qr",
  "status": "pending",
  "provider": {
    "name": "test",
    "operation_id": "test_Qm7Tz2Lp9VxK",
    "kind": "qr",
    "status": "QrTokenCreated",
    "qr_url": "https://pay.sezgir.com/pay/pay_6Jk2Lm9Nq4Rs7Tv1Wx3Yz8Ab?test=1",
    "qr_expires_at": "2026-10-25T09:19:03.512Z"
  }
}
В тестовом режиме provider.qr_url ведёт на страницу оплаты Sezgir Pay, а не в Kaspi: отсканировав такой QR телефоном, вы попадёте на страницу с кнопками симуляции.

Поведение по типам

Тип«Оплатить»«Отклонить»Срок
linksucceeded — если QR ещё не выпущен, он выпустится автоматическиПопытка завершается, ссылка остаётся pending — как в боевом режимеexpires_in; каждый QR — 5 минут
qrsucceededfailedQR — 5 минут
invoicesucceededfailed24 часа
  • Для счёта номер телефона по-прежнему обязателен и проверяется, но никуда не отправляется.
  • Возвраты в тестовом режиме выполняются сразу и всегда успешно.
  • Отмена и истечение срока работают так же, как в боевом режиме.
  • Ответы 202 на возврат, флаг requires_review и ошибки provider_unavailable возникают только при проблемах со связью с Kaspi, поэтому в тестовом режиме их не воспроизвести — предусмотрите их обработку по описанию.

Сценарии для проверки

Перед запуском пройдите эти сценарии в тестовом режиме:

СценарийКак воспроизвестиЧто должно произойти у вас
Успешная оплатаСоздать link, нажать «Оплатить» на странице оплатыЗаказ оплачен по вебхуку payment.succeeded
ОтказСоздать qr, нажать «Отклонить»Заказ не оплачен, покупателю предложено попробовать снова
ИстечениеСоздать link с expires_in: 300 и подождатьЗаказ не удаляется, payment.expired обработан
ОтменаPOST /payments/:id/cancelpayment.canceled обработан; повторная отмена → 409 payment_not_pending
Частичный и полный возвратДва возврата по оплаченному платежуСумма возврата учтена, статус partially_refunded → refunded
Повтор запросаОтправить POST /payments дважды с одним Idempotency-KeyОдин платёж, у второго ответа Idempotent-Replayed: true
Дубль вебхукаОтветить 500 на первую доставку, затем принять повторСобытие не обработано повторно
Неверная подписьИзменить тело или секрет в своём тестеСервер отвечает 400 и ничего не меняет
Недоступный серверВыключить обработчик вебхуков, затем включитьСобытие пришло повторно; сверка через GET /events находит пропущенное

Переход в боевой режим

  1. Подключите кассира Kaspi в разделе Kaspi кабинета и назначьте его сервису (Сервис → Настройки). Без кассира боевые платежи возвращают 503 provider_unavailable.
  2. Создайте боевой ключ sk_live_ (нужна роль администратора) и проверьте его запросом GET /me.
  3. Добавьте боевой вебхук с адресом https:// и сохраните его секрет — он отличается от тестового.
  4. Замените ключ и секрет вебхука в конфигурации продакшена. Код менять не нужно.
  5. Проведите реальный платёж на небольшую сумму и верните его через API — так вы проверите всю цепочку, включая возврат.