Мероприятия и продажа билетов

Коротко

У мероприятия два разных момента оплаты, и делаются они разными инструментами. Предпродажа — ссылка на оплату (без кода) или форма на сайте (через форма-хук). На входе — QR на экране или счёт прямо на телефон гостя, потому что там счёт идёт на секунды. Номер места, сектор, тип билета — всё это кладётся в поле metadata и возвращается обратно в вебхуке. Если мероприятие отменяется, возвраты делаются по каждому счёту.

Предпродажа

Без кода: ссылка на оплату

Самое простое. Делаете по одной ссылке на каждый тип билета:

Ссылки размещаете в Instagram, на афише, в Telegram-канале. Кто оплатил — видно в кабинете. Подробнее: Ссылки на оплату.

Если собираете спонсорские или добровольные взносы, сделайте ссылку, где сумму вводит сам плательщик: Ссылки с открытой суммой.

Форма на сайте

Если у вас есть форма регистрации (имя, телефон, тип билета), привяжите её к оплате. Tilda и любые формы подключаются через форма-хук, писать код не нужно: Tilda и любые формы.

Для собственного сайта хватит одного метода API.

Схема работы по шагам

Продажа билета с сайта:

QR, который сканируют на входе, — это QR вашего билета, а не платежа. Не путайте их.

Какой метод API используется

POST https://api.qut.kz/api/v1/invoices
X-API-Key: qp_live_…
Idempotency-Key: reg-2026-0417-A14

{
  "amount": 8000,
  "kind": "qr",
  "description": "Concert 17.04, стандарт",
  "externalOrderId": "reg-2026-0417-A14",
  "customer": { "name": "Дархан", "phone": "77011234567" },
  "metadata": {
    "event": "concert-2026-04-17",
    "ticketType": "standard",
    "sector": "A",
    "seat": 14
  }
}

description видит клиент: в QR-счёте ограничение 100 символов, в счёте по телефону — 60. Уместите туда название мероприятия и дату.

Стройте Idempotency-Key из номера регистрации — тогда двойное нажатие кнопки «Оплатить» не создаст второй счёт.

Оплата на входе

На входе стоит очередь, поэтому важна скорость. Два пути:

При счёте на телефон гостю приходит push в приложение Kaspi, он подтверждает сразу. Номер в формате 7XXXXXXXXXX. Сравнение: QR-счёт или счёт по телефону.

Окно сканирования QR — около трёх минут. Не создавайте счёт человеку заранее, пока он стоит в очереди: создавайте, когда подошла его очередь, иначе счёт истечёт.

Вариант без кода: выставляйте счёт из кабинета или командой /invoice в Telegram-боте. На входе с телефона бот удобнее.

Массовое выставление счетов

Если продаёте билеты организациям, группам, школьным классам, счета можно выставить одним запросом: POST /api/v1/invoices/bulk, от 1 до 100 счетов за раз.

Каждый элемент проверяется отдельно: если один ошибочный, остальные всё равно создадутся. В ответе видно, какие прошли, а какие упали. Не считайте ответ единым целым — читайте результат по каждому элементу. Подробнее: Массовое создание счетов.

При массовом выставлении давайте каждому элементу свой externalOrderId и свой metadata, иначе не разберётесь, кто оплатил.

Metadata: номер места

На мероприятии metadata — самое полезное поле. Что туда класть:

"metadata": {
  "event": "concert-2026-04-17",
  "ticketType": "vip",
  "sector": "B",
  "row": 3,
  "seat": 12,
  "promoter": "insta",
  "guestName": "Дархан"
}

Что это даёт:

• Всё возвращается в вебхуке invoice.paid — билет выпускаете прямо там
• В выгрузке CSV можно фильтровать: сколько продано по секторам
• Отчёт по промоутерам: какой канал привёл сколько билетов

externalOrderId — отдельное поле, это ваш номер регистрации. Используйте оба: Metadata и номер заказа.

Мероприятие отменилось: массовые возвраты

Если мероприятие не состоялось, возврат делается по каждому счёту:

POST https://api.qut.kz/api/v1/invoices/{id}/refund
{ "reason": "мероприятие отменено" }

Порядок:

1. Соберите список. Через GET /api/v1/invoices или выгрузкой CSV из кабинета. Отберите счета в статусе paid.
2. Сначала объявите. Напишите участникам до начала возвратов, иначе поддержку завалит сообщениями.
3. Делайте по одному. Метода массового возврата нет, на каждый счёт отдельный запрос. Ставьте паузы, чтобы не упереться в ограничение частоты.
4. Ведите протокол. Записывайте, какие возвраты прошли, а какие упали.
5. Пришёл refund_unknown — не повторяйте. Сначала прочитайте состояние счёта, иначе можно вернуть дважды. Подробнее: API возвратов.

Если мероприятие переносится, чаще и проще объявить билеты действительными на новую дату, а не возвращать деньги.

На что обратить внимание

• Поздние оплаты. Если деньги пришли после того, как счёт стал expired, событие придёт с признаком late: true. На входе это живой человек — пропустите его или сразу верните деньги.
• Учтите суточную защиту. В день старта продаж количество счетов резко подскакивает. Суточное число — не бизнес-лимит, а защита от зациклившейся интеграции, но упёршись в него вы получите ошибку tariff_daily_burst. Проверьте тариф заранее: Какой тариф выбрать.
• На входе нужен интернет. Без сети счёт не создастся. Если Wi-Fi на площадке слабый, держите наготове второй телефон с мобильным интернетом.
• Протестируйте заранее. Не за день до мероприятия, а за неделю прогоните полный цикл в песочнице: Как протестировать интеграцию.
• Деньги приходят напрямую на ваш счёт Kaspi, у нас не задерживаются.

Вопросы и ответы

Кто выпускает сам билет? Вы. Мы обрабатываем только оплату. Билет, его QR и проверку на входе делаете вы сами или через билетную систему.

Если человек берёт два билета? Выставьте один счёт: в amount общую сумму, в metadata список мест. Либо отдельный счёт на каждое место — так удобнее, если придётся возвращать деньги.

Есть ли срок на возврат проданного билета? Да, у возвратов свой срок. Билет, проданный давно, вернуть может не получиться: API возвратов.

Нужен ли на входе сканер QR? Для оплаты не нужен — гость сканирует своим телефоном. Для проверки билетов он может понадобиться вашей системе.

Регистрация бесплатная, но много неявок. Что делать? Берите символическую сумму (1 000-2 000 ₸) или используйте схему с залогом — возвращаете его при явке. Похожая схема: Салон красоты и барбершоп.