Как принимать платежи в USDT в Telegram-боте
Telegram-боты: одно из лучших мест для продажи цифровых товаров и одно из худших для прикручивания традиционной оплаты. Нет формы для карты, нет страницы оплаты, которая выглядела бы родной, а пользователи не любят, когда их выбрасывает в браузер. Криптоплатёжный шлюз с обычным REST API подходит гораздо лучше: бот создаёт счёт, публикует платёжные данные сообщением и реагирует, когда вебхук сообщает, что деньги пришли.
Что нужно перед началом
- Токен бота от @BotFather.
- Сервер, который может принимать HTTPS-запросы. Бэкенд бота и приёмник вебхуков могут быть одним приложением.
- Аккаунт VisualPay с включённой двухфакторной аутентификацией, созданный мерчант и API-ключ мерчанта, скопированный из панели. Регистрация и первый мерчант бесплатны, проходить проверку личности заранее не нужно.
- Адрес кошелька под вашим контролем для каждой монеты и сети, которые вы планируете принимать, указанный в настройках мерчанта.
Общая схема
Прежде чем писать код, полезно точно определить, кто что делает, потому что именно из-за ошибок здесь платежи в ботах теряют деньги:
- Пользователь выбирает товар в боте.
- Ваш бэкенд (ни в коем случае не клиент) вызывает шлюз, чтобы создать транзакцию.
- Бот публикует сообщением платёжный адрес, точную сумму в USDT и срок оплаты.
- Пользователь платит со своего кошелька.
- Шлюз обнаруживает платёж и вызывает ваш вебхук.
- Бэкенд проверяет статус, отмечает заказ оплаченным и поручает боту выдать товар.
Обратите внимание: шаг 6 запускается шагом 5, а не действиями пользователя. Кнопка «Я оплатил» в чате годится как сигнал перепроверить статус, но она никогда не должна быть тем, что выдаёт товар.
Шаг 1. Спросите, какая сеть
USDT существует в нескольких сетях, и они не взаимозаменяемы. Отправьте USDT из TRC20 на адрес ERC20, и деньги пропадут. Поэтому сделайте выбор сети явным, с помощью inline-клавиатуры, а не свободного текста:
{
"inline_keyboard": [
[{ "text": "USDT · TRC20 (Tron)", "callback_data": "pay:USDT:trc20" }],
[{ "text": "USDT · BEP20 (BSC)", "callback_data": "pay:USDT:bep20" }],
[{ "text": "USDT · ERC20 (Ethereum)", "callback_data": "pay:USDT:erc20" }]
]
}
Практический совет: ставьте TRC20 первым. Сетевые комиссии в Tron достаточно низкие, поэтому для небольших покупок это обычно самый удобный вариант, а боты в основном и продают недорогие товары.
Шаг 2. Создайте транзакцию на сервере
Когда приходит callback query, бэкенд создаёт счёт. API-ключ передаётся в заголовке и никогда не покидает ваш сервер:
const res = await fetch(
'https://visualpay.net/api/v1/merchant/transaction/create',
{
method: 'POST',
headers: {
'x-api-key': process.env.VISUALPAY_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
currency_symbol: 'USDT',
network_code: 'trc20',
amount_usd: 25.5,
ttl: 20,
order_id: order.id,
comment: `Telegram user ${ctx.from.id}`,
}),
}
);
const tx = await res.json();
Над значениями нескольких полей стоит подумать, а не копировать их:
ttl: окно оплаты в минутах и одновременно срок, на который фиксируется курс. Двадцать минут подходят ботам как значение по умолчанию: этого хватает, чтобы открыть приложение кошелька, и это достаточно мало, чтобы ограничить риск изменения курса.order_id: ваш собственный идентификатор. Сохраните его вместе с пользователем и чатом Telegram, чтобы вебхук смог найти нужный диалог.comment: свободный текст, который отображается в вашей панели. Пригодится поддержке, когда пользователь напишет: «Я оплатил и ничего не получил».
Сразу сохраните полученный трек-код с привязкой к заказу. По нему вы потом будете искать платёж.
Шаг 3. Покажите счёт сообщением
Поскольку шлюз возвращает платёжные данные, а не перенаправляет пользователя, вы можете показать их естественным для мессенджера способом. Оформите сумму и адрес моноширинным шрифтом, чтобы в Telegram их можно было скопировать одним касанием, и не разрывайте адрес переносом строки:
Отправьте ровно:
1580.70 USDT
Сеть: TRC20 (Tron)
На адрес:
TXk...c72E
⏱ Истекает через 20 минут.
Два дополнения окупаются сразу. Прикрепите QR-код, чтобы пользователи мобильных устройств могли отсканировать его с другого устройства. И добавьте кнопку «Проверить платёж», которая вызывает метод статуса. Она нужна не для выдачи товара, а чтобы нетерпеливому пользователю было что нажать вместо сообщения в поддержку.
Шаг 4. Обработайте вебхук
Именно здесь заказ действительно завершается. Адрес должен работать по HTTPS, а обработчик должен быть скучным и осторожным:
app.post('/webhooks/visualpay', async (req, res) => {
// 1. Отвечаем быстро, чтобы шлюз не ждал.
res.sendStatus(200);
const { tracking_code } = req.body;
// 2. Перепроверяем на сервере и не доверяем содержимому запроса.
const status = await verifyWithGateway(tracking_code);
if (status !== 'confirmed') return;
// 3. Идемпотентность: вебхук может прийти больше одного раза.
const order = await orders.findByTrackingCode(tracking_code);
if (!order || order.fulfilled) return;
await orders.markFulfilled(order.id);
await bot.telegram.sendMessage(order.chat_id, 'Платёж получен. Вот ваш товар: …');
});
В трёх пронумерованных комментариях весь урок. Отвечайте быстро, потому что медленные обработчики вебхуков вызывают повторные отправки. Перепроверяйте статус через API и не доверяйте телу запроса: это стоит одного вызова и убирает целый класс подделок. Делайте обработку идемпотентной, потому что повторный вебхук, выдавший товар дважды, это реальная ошибка, которая обязательно случится в продакшене.
Шаг 5. Обработайте неудачные сценарии
Судьба бота зависит от того, что происходит, когда всё идёт не по плану:
- Истёк срок. Окно закрылось без оплаты. Ничего не списано. Отредактируйте сообщение, сообщите об этом и предложите кнопку «Попробовать снова», которая создаёт новую транзакцию по текущему курсу.
- Недоплата. Если она укладывается в допуск, заданный в настройках мерчанта, платёж проходит, а зачисляемая сумма пересчитывается от фактически поступившей. Если нет, прямо сообщите пользователю, сколько пришло и сколько ожидалось.
- Переплата. Платёж принимается и записывается как переплата. Заранее определите правила (зачислить разницу на баланс пользователя или вернуть вручную) и сообщите о них в боте до оплаты.
- Оплата с опозданием. Кто-то платит через минуту после истечения срока. Метод перепроверки повторно проверяет платёж в блокчейне для истёкшей или отменённой транзакции, так что ситуацию можно исправить без обращения в поддержку.
Получение выплат
Поскольку VisualPay работает по некастодиальной модели, подтверждённые платежи не лежат на балансе провайдера в ожидании вашего вывода. Как только баланс по сети превышает порог выплаты, средства автоматически уходят на указанный вами адрес кошелька, обычно меньше чем за минуту, и удерживается только сетевая комиссия самого блокчейна.
О безопасности, к которой стоит отнестись серьёзно
- API-ключ должен храниться в переменной окружения на вашем сервере. Никогда в клиентском коде бота, никогда в репозитории, никогда в сообщении.
- Адреса вебхуков должны работать по HTTPS, а путь должен быть неочевидным, а не таким, который легко угадать.
- Ограничьте частоту команды, создающей транзакции. Без этого один пользователь может наплодить сотни открытых счетов.
- Делайте сверку по расписанию. Ночное задание, которое получает список транзакций и сравнивает его с вашими заказами, выявляет редкие случаи, когда вебхук был полностью пропущен.
Почему эта схема подходит ботам
Не нужно устанавливать плагин, обновлять SDK и прерывать диалог редиректом. Бот остаётся ботом: ветка сообщений, в которой появляется счёт, он оплачивается и превращается в выданный товар. Всё, что делает шлюз (фиксация курса, выдача адреса, мониторинг сети, выплата), происходит за двумя HTTP-вызовами и одним вебхуком.
Начните принимать USDT и USDC уже сегодня
Начните без KYC, оставьте оплату на своём сайте и получайте средства на собственный кошелёк. Регистрация и первый мерчант бесплатны.