Инструкция по интеграции и настройке способов оплаты CUSTOM и CUSTOM_LINK

Документ предназначен для разработчиков, подключающих собственную платёжную систему к платформе BOT-T через способы оплаты CUSTOM и CUSTOM_LINK.

Полезные ссылки:

Общее: код заказа (order_id)

Идентификатор заказа имеет формат:

TYPE-MODEL_ID-ITEM_ID

TYPE — тип операции: u (пополнение баланса), o (заказ в боте без корзины), c (заказ в боте с корзиной), r (пополнение/списание), s (подписки).
MODEL_ID — уникальный идентификатор сделки (число).
ITEM_ID — идентификатор способа оплаты.
Разделитель — дефис -.

Пример: u-12345-67 — пополнение баланса, сделка 12345, способ оплаты 67.

1. CUSTOM — оплата через ваш обработчик по данным от клиента

Назначение

Клиент вводит данные (номер карты, реквизиты, код и т.п.) в боте. Эти данные отправляются на ваш сервер; вы проверяете платёж и отвечаете, засчитывать ли оплату.

Настройка в ЛК

Ссылка на обработчик — полный HTTPS-адрес вашего скрипта, например: https://your-site.com/payment-handler.php
Label — подпись поля ввода для клиента (в т.ч. в веб-версии), например: «Номер карты» или «Код оплаты»

В разделе «Дизайн» настраивается текст сообщения («Информация») и кнопка.

Процесс работы

Клиент выбирает способ оплаты CUSTOM.
Бот показывает текст из дизайна и ожидает ввод от клиента.
Введённые данные бот отправляет на ваш обработчик POST-запросом.

Что приходит на ваш обработчик (POST)

Параметр	Описание
`code`	Данные, введённые клиентом
`id`	Полный номер заказа в формате `TYPE-MODEL_ID-ITEM_ID`
`bot_id`	Уникальный идентификатор бота
`currency`	Код валюты (RUB, USD, EUR и т.д.) — обязательно проверять

Ответ вашего обработчика (JSON)

Сервер BOT-T ожидает ответ в формате JSON с полями:

Поле	Тип	Описание
`id`	string	Уникальный идентификатор транзакции в вашей системе
`sum`	int	Фактическая сумма поступления в минимальных единицах (копейки, центы)
`status`	bool	`true` — оплату засчитать, `false` — отменить заказ

Особенности:

Если вернуть id = "-1", сервер подождёт 3 секунды и повторит запрос (удобно для очередей).
При status = true заказ засчитывается; при status = false — отменяется.
Если вернуть sum меньше суммы заказа: для заказа — отмена; для пополнения баланса — зачисляется указанная меньшая сумма.
Все запросы можно отслеживать в логе способа оплаты в личном кабинете.

Пример ответа (успех)

{
  "id": "tx-12345",
  "sum": 10050,
  "status": true
}

Пример ответа (отказ)

{
  "id": "tx-12345",
  "sum": 0,
  "status": false
}

Пример ответа (повторить запрос через 3 сек)

{
  "id": "-1",
  "sum": 0,
  "status": false
}

2. CUSTOM_LINK — оплата по ссылке на ваш сайт и webhook

Назначение

Клиенту выдаётся ссылка на ваш сайт с параметрами заказа. После оплаты у вас ваш сервер отправляет уведомление (webhook) на API BOT-T — платформа засчитывает платёж.

Настройка в ЛК

Ссылка — базовый URL вашей страницы оплаты, к которому будут добавлены GET-параметры.
Пример: https://your-site.com/pay?
Итоговая ссылка будет вида: https://your-site.com/pay?id=...&order_id=...&sum=...&cur=...&sign=...

Опционально в настройках способа оплаты можно включить режим «веб-ссылка» (открытие в Web App Telegram).

Как формируется ссылка на оплату

Платформа добавляет к вашему URL следующие GET-параметры:

Параметр	Описание
`id`	Номер сделки — только MODEL_ID (вторая часть order_id)
`order_id`	Полный номер заказа `TYPE-MODEL_ID-ITEM_ID`
`sum`	Сумма в минимальных единицах (копейки/центы)
`cur`	Код валюты (RUB, USD и т.д.)
`sign`	Подпись для проверки подлинности (см. ниже)

Проверка подписи на вашей стороне (при переходе клиента)

Подпись в ссылке считается по формуле:

Разделитель: : (двоеточие).
Строка для подписи: id:sum:currency:TOKEN
- id — только MODEL_ID (число, вторая часть order_id);
- sum — сумма в копейках/центах;
- currency — код валюты;
- TOKEN — токен бота из настроек BotFather.

Формула: sign = md5(id . ':' . sum . ':' . currency . ':' . token).

Ваш обработчик страницы оплаты должен всегда проверять подпись, сверяя переданный sign с вычисленным значением. Токен бота храните в секрете на сервере.

Webhook: уведомление BOT-T об успешной оплате

После того как клиент оплатил заказ в вашей системе, ваш сервер должен отправить POST-запрос на API BOT-T:

URL: https://api.bot-t.com/payment/custom-link
(или ваш домен API, если развёрнут свой экземпляр: https://<ваш-домен>/api/payment/custom-link)

Метод: POST

Параметры (тело запроса):

Параметр	Тип	Описание
`order_id`	string	Полный номер заказа `TYPE-MODEL_ID-ITEM_ID`
`sum`	int	Сумма платежа в минимальных единицах (копейки/центы)
`currency`	string	Код валюты (RUB, USD и т.д.)
`sign`	string	Подпись (см. ниже)

Подпись для webhook

При webhook используется полный order_id (не только model_id):

sign = md5(order_id . ':' . sum . ':' . currency . ':' . token)

Вместо token может использоваться секретный ключ бота (если настроен): тогда
sign = md5(order_id . ':' . sum . ':' . currency . ':' . secret_key).

Платформа проверяет оба варианта (токен и секретный ключ).

Пример генерации подписи (PHP) для webhook

$order_id = 'u-12345-67';  // полный order_id
$sum = 10050;
$currency = 'RUB';
$token = 'YOUR_BOT_TOKEN'; // или секретный ключ бота

$sign = md5($order_id . ':' . $sum . ':' . $currency . ':' . $token);

Пример cURL для webhook

curl -X POST "https://api.bot-t.com/payment/custom-link" \
  -d "order_id=u-12345-67" \
  -d "sum=10050" \
  -d "currency=RUB" \
  -d "sign=XXXXXXXXXXXX"

Ответ API на webhook

Успех: HTTP 200, тело вида {"status":"ok"}.
Ошибка: HTTP 400, тело с полями error, description (текст ошибки). В логе способа оплаты в ЛК можно посмотреть детали (например, «Неверная подпись»).

Альтернатива общему webhook

Вместо отправки на общий эндпоинт payment/custom-link можно использовать отдельные API для разных типов операций (пополнение баланса, заказ без корзины, заказ с корзиной и т.д.). Актуальные ссылки и методы описаны в разделах документации по управлению балансами и оплате заказов (см. ссылки в FAQ CUSTOM_LINK).

Краткое сравнение

Аспект	CUSTOM	CUSTOM_LINK
Инициатор данных	Клиент вводит в боте	Клиент переходит по ссылке на ваш сайт
Ваш сервер	Принимает POST с `code`, `id`, `bot_id`, `currency` и возвращает JSON `id`, `sum`, `status`	Отдаёт страницу оплаты (проверяя `sign` из GET), после оплаты шлёт POST на API BOT-T
Подпись	Не используется	В ссылке: по `id` (model_id); в webhook: по полному `order_id`
Эндпоинт BOT-T	Нет (BOT-T ходит к вам)	POST на `.../payment/custom-link` от вас к BOT-T

Способ оплаты

Инструкция по интеграции и настройке способов оплаты CUSTOM и CUSTOM_LINK

Общее: код заказа (order_id)

1. CUSTOM — оплата через ваш обработчик по данным от клиента

Назначение

Настройка в ЛК

Процесс работы

Что приходит на ваш обработчик (POST)

Ответ вашего обработчика (JSON)

Пример ответа (успех)

Пример ответа (отказ)

Пример ответа (повторить запрос через 3 сек)

2. CUSTOM_LINK — оплата по ссылке на ваш сайт и webhook

Назначение

Настройка в ЛК

Как формируется ссылка на оплату

Проверка подписи на вашей стороне (при переходе клиента)

Webhook: уведомление BOT-T об успешной оплате

Подпись для webhook

Пример генерации подписи (PHP) для webhook

Пример cURL для webhook

Ответ API на webhook

Альтернатива общему webhook

Краткое сравнение

Рекомендации