Коротко
Мы опрашиваем Kaspi о статусе счетов, и этот опрос идёт по очереди, а не мгновенно. Поэтому между моментом, когда покупатель подтвердил оплату, и моментом, когда ваша система узнала об этом, всегда есть небольшая задержка. На практике webhook обычно приходит в течение пяти секунд. Если ваш сценарий чувствителен к задержке (турникет, шлагбаум, вендинг, прямой эфир), ведите два канала параллельно: ждите webhook и одновременно опрашивайте GET /api/v1/invoices/{id} — что придёт первым, то и принимайте.
Как устроена проверка
Poller — внутренний процесс, который спрашивает у Kaspi статусы счетов. Он делает круг каждые 3 секунды, но за один круг опрашивает не все открытые счета: частота зависит от возраста счёта.
| Возраст счёта | Как часто проверяется |
|---|---|
| Младше 3 минут | Каждый круг, то есть максимально часто |
| От 3 до 30 минут | Примерно раз в 20 секунд |
| Старше 30 минут | Примерно раз в 90 секунд |
Очередь начинается с самого свежего счёта. Логика простая: только что выставленный счёт с большой вероятностью оплачивают прямо сейчас, а счёт часовой давности чаще всего уже не оплатят. Поэтому новые счета подтверждаются быстрее всего.
Практический вывод: если покупатель идёт платить сразу после выставления счёта, подтверждение будет самым быстрым. Если счёт выставили заранее, а оплатили через полчаса, подтверждение может задержаться до 90 секунд.
Сколько это занимает на практике
В обычной ситуации после того, как покупатель отсканировал QR и подтвердил оплату в Kaspi, событие invoice.paid приходит на ваш webhook-адрес примерно за пять секунд. Это наблюдаемое среднее, а не гарантия: нагрузка на стороне Kaspi и состояние сети могут его увеличить.
Важная деталь. Kaspi не передаёт в payload точное время оплаты. То есть измерить промежуток «от подтверждения покупателем до получения нами» по данным Kaspi невозможно — такого поля просто нет. Любой расчёт «реальной задержки» будет оценкой. На своей стороне вы можете измерить только интервал между созданием счёта и приходом webhook, а в него входит ещё и время, пока покупатель раздумывал.
Сценарии, чувствительные к задержке
Если сразу после подтверждения оплаты должно произойти физическое действие — открыться шлагбаум, автомат выдать товар, в эфире подтвердиться заказ — ведите два канала параллельно:
- Webhook — основной канал. Вы узнаёте о смене статуса, ничего не спрашивая.
GET /api/v1/invoices/{id}— резервный канал. Первые 1-2 минуты после создания счёта опрашивайте статус раз в несколько секунд.
Что первым скажет «paid», то и принимайте, и выполняйте действие. Чтобы не выполнить его дважды, когда придёт второй канал, обработка должна быть идемпотентной: записывайте в журнал пару (id счёта, статус) и, если такая пара уже обработана, ничего не делайте.
Не опрашивайте вечно. Разумный режим: первые 2 минуты — раз в 2-3 секунды, дальше реже, а после истечения expiresAt остановиться. При слишком частых запросах вы получите rate_limited или request_rate_limited.
Что задержкой не является
Не всякая задержка — вина poller. Сначала исключите вот это:
| Признак | Что происходит на самом деле |
|---|---|
| Счёт вообще не становится paid | Покупатель ещё не заплатил или вы в тестовом режиме |
| Webhook не приходит, но в кабинете счёт paid | Проблема на стороне webhook: Вебхук не приходит |
| В кабинете статус сразу, а в вашей системе поздно | Забита ваша собственная очередь, проверьте свою обработку |
| Счёт закрыт, а деньги пришли | Это поздняя оплата, приходит с признаком late: true |
| Денег не видно на счёте Kaspi | Это другая тема: Когда и куда приходят деньги |
Отдельно про позднюю оплату: деньги могут прийти по счёту в статусе cancelled или expired, и тогда событие invoice.paid придёт позже с признаком late: true. Не игнорируйте такой счёт — либо окажите услугу, либо верните деньги.
В песочнице задержки нет
В режиме песочницы Kaspi не вызывается, статус вы ставите сами через POST /api/v1/invoices/{id}/simulate. Поэтому там подтверждение мгновенное. Это особенность тестовой среды — не оценивайте по песочнице скорость боевого режима.
Вопросы и ответы
Можно ли изменить частоту работы poller? Нет, она общая для всех и подстраивается под возраст счёта автоматически.
Почему один счёт подтвердился за 3 секунды, а другой за 40? У них был разный возраст. Свежий счёт проверяется каждый круг, а получасовой — раз в 90 секунд.
Если я буду чаще опрашивать статус, подтверждение ускорится? Немного да: ваш запрос GET /invoices/{id} не зависит от очереди poller. Но не перебарщивайте, иначе получите 429. Лучший вариант — два канала параллельно.
Можете назвать точную задержку в секундах? Поскольку Kaspi не передаёт время оплаты, промежуток «от подтверждения покупателем до нас» не может измерить никто. Измеримо только время от создания счёта до прихода webhook.
Что показывать покупателю, пока идёт ожидание? После создания счёта покажите экран ожидания и опрашивайте статус в фоне. Когда придёт подтверждение — смените экран. Технические тексты ошибок покупателю показывать не надо.