Коротко
Форм-хук — персональный адрес вашей организации. Как только форма отправляет на него данные, Qut Pay создаёт счёт. Писать код не нужно: в Tilda вы указываете этот адрес в приёмнике «Webhook», в обычной HTML-форме — в атрибуте action.
Адрес выглядит так: https://api.qut.kz/hooks/form/<токен>. Получить его можно в кабинете: Интеграции → форм-хуки → создать.
В ответ приходит ссылка на страницу оплаты. Если включить режим redirect, покупатель попадает на оплату сразу после отправки формы.
Как настроить
- Кабинет → Интеграции → создайте форм-хук и дайте ему имя (2-60 символов).
- Скопируйте адрес хука.
- В Tilda: в настройках формы подключите приёмник «Webhook» и вставьте адрес. В обычной форме:
<form method="post" action="https://api.qut.kz/hooks/form/…">. - Отправьте форму один раз. В карточке хука видно число пришедших запросов, число созданных счетов и последнюю ошибку.
На организацию можно завести до 20 хуков. Удобно делать отдельный хук на каждую страницу, товар или кампанию — тогда и отчётность разделяется сама собой.
Хук принимает и application/json, и обычный application/x-www-form-urlencoded. Тело запроса — не больше 32 КБ.
Сопоставление полей
Вручную сопоставлять поля не нужно: хук сам распознаёт самые распространённые имена. Регистр значения не имеет.
| Что | Принимаемые имена |
|---|---|
| Сумма | amount, sum, summa, price, total, paymentsum, payment.amount, сумма |
| Телефон | phone, tel, telephone, mobile, whatsapp, телефон |
email, e-mail, mail, почта | |
| Имя | name, fio, fullname, имя, аты |
| Описание | description, comment, product, service, tariff, plan, товар, услуга |
| Номер заказа | orderid, order_id, externalorderid, payment.orderid, tranid, formid |
Вложенные структуры Tilda тоже разбираются: поля вида payment[amount] разворачиваются на один уровень, а если пришёл список products, сумма считается по нему (цена × количество) и используется как сумма счёта.
Если сумма не найдена, хук отвечает ошибкой invalid_amount — «поле суммы не найдено». Переименуйте поле формы в одно из перечисленных или задайте фиксированную сумму в настройках хука.
Телефон приводится к формату 7XXXXXXXXXX автоматически — клиент может написать его через дефисы, скобки или начиная с восьмёрки.
Значения по умолчанию
В карточке хука задаётся несколько параметров по умолчанию:
| Параметр | Что делает |
|---|---|
| Сумма | Фиксированная сумма. Если она задана, сумма из формы игнорируется — удобно для одной услуги или подписки |
| Описание | Текст, который видит покупатель. Используется, когда описания в форме нет. До 60 символов |
| Тип счёта | qr — QR и страница оплаты; phone — счёт уходит прямо в приложение Kaspi покупателя |
| successUrl | Страница, куда покупатель попадёт после оплаты. Только http(s) |
| Redirect | Вместо JSON-ответа покупатель сразу перенаправляется на страницу оплаты |
При типе phone поле телефона в форме обязательно, а сумма округляется до целых тенге. Если телефон не пришёл, хук создаст обычный QR-счёт.
Режим redirect
Есть два способа работы.
Ответ JSON (по умолчанию). Хук возвращает HTTP 201 и тело:
{ "ok": true, "invoiceId": "inv_…", "status": "pending",
"payUrl": "https://api.qut.kz/pay/inv_…", "expiresAt": "…" }Это подходит для приёмника webhook в Tilda, для n8n, для вашего сервера: берёте payUrl и отправляете клиента туда.
Перенаправление. Если в настройках хука включён Redirect (или вы добавили к адресу ?redirect=1), вместо ответа приходит 302, и браузер уводит покупателя прямо на оплату. Для обычной HTML-формы это самый короткий путь:
<form method="post" action="https://api.qut.kz/hooks/form/ТОКЕН?redirect=1">
<input name="amount" value="5000" type="hidden">
<input name="name" placeholder="Имя">
<input name="phone" placeholder="Телефон">
<button type="submit">Оплатить</button>
</form>Собственный механизм webhook в Tilda страницу не меняет, поэтому там используют не redirect, а payUrl из ответа — либо ставят обычный блок с формой, которая отправляется прямо на адрес хука.
Проверочный запрос Tilda
Сохраняя адрес webhook, Tilda отправляет пустой запрос с признаком test. Хук распознаёт его, отвечает { "ok": true, "test": true } и счёт не создаёт. Кнопка «Проверить» в Tilda проходит нормально, а в кабинете не появляется лишний счёт.
Остановка хука и смена токена
Адрес хука не секретный, но он открыт: создать счёт может любой, кто его знает. Поэтому:
- Остановка. Переведите хук в состояние «остановлен». Запросы начнут получать
hook_paused(HTTP 410), счета создаваться перестанут. Так делают, когда кампания закончилась или страница снята. - Смена токена. Если адрес попал не в те руки, обновите токен. Старый адрес перестаёт работать немедленно — не забудьте обновить адрес в форме.
- Удаление. Если хук больше не нужен, удалите его.
В счетах, созданных через хук, в metadata остаётся идентификатор хука и признак source: "form" — по нему в отчётности видно, из какой формы пришёл платёж.
Как читать ошибки
| Ошибка | HTTP | Что произошло |
|---|---|---|
hook_not_found | 404 | Неверный адрес или токен был заменён |
hook_paused | 410 | Хук остановлен, включите его в кабинете |
invalid_amount | 422 | Поле суммы не найдено или это не число |
invalid_phone | 422 | Неверный формат телефона |
tariff_limit_reached | 429 | Исчерпан месячный лимит счетов |
Последняя ошибка видна и в карточке хука — при настройке формы это самый быстрый способ понять, что не так. Полный список: Каталог ошибок.
Вопросы и ответы
Сайт не на Tilda, а на другом конструкторе. Подойдёт? Да. Годится всё, что умеет отправлять POST: Webflow, форма WordPress, свёрстанный вручную HTML, автоматизация после Google Forms.
Форма отправилась, а счёта нет. Посмотрите строку «последняя ошибка» в карточке хука. Чаще всего дело в том, что имя поля суммы не распознано или форма прислала пустую сумму.
Как я узнаю об оплате? Уведомление приходит в кабинет, в Telegram-бота или на ваш вебхук. Если нужна автоматизация — заведите события в n8n: Автоматизация в n8n.
Можно ли одной формой продавать разные товары? Да: пусть из формы приходят и описание, и сумма. Один хук обработает все позиции.
Нужно, чтобы сумму вводил сам покупатель. Так можно? Можно — оставьте поле суммы в форме открытым и не задавайте фиксированную сумму в настройках хука.
Этот способ действительно обходится без программиста? Да. Есть и другие пути начать без кода: Нет программиста — как начать.