# Tilda и любые формы: приём оплаты без кода

> Форм-хук — отдельный адрес, на который форма отправляет данные, и счёт создаётся в момент отправки. Сопоставление полей, режим redirect, настройка в кабинете и остановка хука.

## Коротко

**Форм-хук** — персональный адрес вашей организации. Как только форма отправляет на него данные, Qut Pay создаёт счёт. Писать код не нужно: в Tilda вы указываете этот адрес в приёмнике «Webhook», в обычной HTML-форме — в атрибуте `action`.

Адрес выглядит так: `https://api.qut.kz/hooks/form/<токен>`. Получить его можно в кабинете: **Интеграции** → форм-хуки → создать.

В ответ приходит ссылка на страницу оплаты. Если включить **режим redirect**, покупатель попадает на оплату сразу после отправки формы.

## Как настроить

1. Кабинет → **Интеграции** → создайте форм-хук и дайте ему имя (2-60 символов).
2. Скопируйте адрес хука.
3. В Tilda: в настройках формы подключите приёмник «Webhook» и вставьте адрес. В обычной форме: `<form method="post" action="https://api.qut.kz/hooks/form/…">`.
4. Отправьте форму один раз. В карточке хука видно число пришедших запросов, число созданных счетов и последнюю ошибку.

На организацию можно завести **до 20 хуков**. Удобно делать отдельный хук на каждую страницу, товар или кампанию — тогда и отчётность разделяется сама собой.

Хук принимает и `application/json`, и обычный `application/x-www-form-urlencoded`. Тело запроса — не больше 32 КБ.

## Сопоставление полей

Вручную сопоставлять поля не нужно: хук сам распознаёт самые распространённые имена. Регистр значения не имеет.

| Что | Принимаемые имена |
|---|---|
| Сумма | `amount`, `sum`, `summa`, `price`, `total`, `paymentsum`, `payment.amount`, `сумма` |
| Телефон | `phone`, `tel`, `telephone`, `mobile`, `whatsapp`, `телефон` |
| Email | `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 и тело:

```json
{ "ok": true, "invoiceId": "inv_…", "status": "pending",
  "payUrl": "https://api.qut.kz/pay/inv_…", "expiresAt": "…" }
```

Это подходит для приёмника webhook в Tilda, для n8n, для вашего сервера: берёте `payUrl` и отправляете клиента туда.

**Перенаправление.** Если в настройках хука включён Redirect (или вы добавили к адресу `?redirect=1`), вместо ответа приходит 302, и браузер уводит покупателя прямо на оплату. Для обычной HTML-формы это самый короткий путь:

```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 | Исчерпан месячный лимит счетов |

Последняя ошибка видна и в карточке хука — при настройке формы это самый быстрый способ понять, что не так. Полный список: [Каталог ошибок](/kb/ru/error-catalog).

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

**Сайт не на Tilda, а на другом конструкторе. Подойдёт?** Да. Годится всё, что умеет отправлять POST: Webflow, форма WordPress, свёрстанный вручную HTML, автоматизация после Google Forms.

**Форма отправилась, а счёта нет.** Посмотрите строку «последняя ошибка» в карточке хука. Чаще всего дело в том, что имя поля суммы не распознано или форма прислала пустую сумму.

**Как я узнаю об оплате?** Уведомление приходит в кабинет, в Telegram-бота или на ваш вебхук. Если нужна автоматизация — заведите события в n8n: [Автоматизация в n8n](/kb/ru/n8n).

**Можно ли одной формой продавать разные товары?** Да: пусть из формы приходят и описание, и сумма. Один хук обработает все позиции.

**Нужно, чтобы сумму вводил сам покупатель. Так можно?** Можно — оставьте поле суммы в форме открытым и не задавайте фиксированную сумму в настройках хука.

**Этот способ действительно обходится без программиста?** Да. Есть и другие пути начать без кода: [Нет программиста — как начать](/kb/ru/no-developer).