Подключение Crypto Pay API к Telegram-боту: полное руководство для новичков

Crypto Pay — это официальная платежная система от @CryptoBot (send.tg), которая позволяет любому Telegram-боту или веб-сервису принимать оплату в криптовалюте без посредников и с минимальными комиссиями. Вы создаёте счёт (invoice) через API, отправляете пользователю ссылку, он платит прямо в приложении Crypto Bot — и вы мгновенно получаете деньги на баланс своего приложения.

Поддерживаемые активы (mainnet 2026):
USDT, TON, BTC, ETH, LTC, BNB, TRX, USDC (и тестовая JET в testnet).

Можно принимать разовые оплаты, оплату за доступ по времени (подписки через логику вашего бота), отправлять чеки и даже переводить монеты пользователям обратно.

## 1. Получение API-токена (тестового и боевого)

Тестовая среда (рекомендуется начать с неё):

1. Откройте бота @CryptoTestnetBot.
2. Напишите /pay или нажмите кнопку Crypto Pay.
3. Нажмите Create App → введите название (например, «MyTestBot») → получите токен вида 12345:ABCdef....
4. Сохраните токен — он будет работать только на https://testnet-pay.crypt.bot/api/.

Боевая среда:

1. Откройте @CryptoBot.
2. Перейдите в Crypto Pay → Create App.
3. Получите токен (он отличается от тестового).
4. Базовый URL: https://pay.crypt.bot/api/.

Важно: Токен передаётся только в заголовке Crypto-Pay-API-Token. Никогда не публикуйте его в коде публичных репозиториев!

## 2. Как тестировать без риска

• В testnet все платежи симулируются. Вы сами можете «оплатить» счёт в тестовом боте.
• Баланс пополняется тестовыми монетами JET (и другими) через меню CryptoTestnetBot.
• Все методы и форматы ответов полностью идентичны продакшену.
• После тестов просто смените URL и токен — код остаётся тем же.

## 3. Основной метод: создание разового счёта (createInvoice)

POST https://pay.crypt.bot/api/createInvoice (или testnet)

Минимальные параметры (JSON):

{
  "asset": "USDT",
  "amount": "9.99",
  "description": "Премиум-доступ на 30 дней",
  "payload": "user_123_order_456",   // ваш внутренний ID
  "expires_in": 3600                 // 1 час на оплату
}

Полный список параметров (все реальные на февраль 2026):

• currency_type: "crypto" (по умолчанию) или "fiat" (тогда amount в USD/EUR/RUB и т.д.)
• accepted_assets: "USDT,TON,BTC" (если fiat)
• hidden_message: текст, который увидит пользователь после оплаты
• paid_btn_name + paid_btn_url: кнопка после оплаты («Открыть бота», «Вернуться» и т.д.)
• allow_comments, allow_anonymous
• swap_to: автообмен в USDT/TON после оплаты (новинка 2025)

Ответ содержит:

• invoice_id
• bot_invoice_url — главная ссылка для оплаты
• mini_app_invoice_url, web_app_invoice_url (для Mini Apps)

Пример отправки ссылки пользователю в боте (aiogram 3.x):

await message.answer(
    "Оплатите доступ:",
    reply_markup=InlineKeyboardMarkup(inline_keyboard=[[
        InlineKeyboardButton(text="Оплатить 9.99 USDT", url=invoice.bot_invoice_url)
    ]])
)

## 4. Как принимать подписки (рекуррентные платежи)

Crypto Pay не имеет встроенных recurring-профилей (как Stripe), но это легко реализуется на стороне вашего бота:

Вариант 1 (самый популярный):

1. Пользователь выбирает подписку (1 месяц / 3 месяца / год).
2. Бот создаёт invoice на соответствующую сумму.
3. При оплате (webhook) записываете в БД: user_id, expires_at = now + 30 дней.
4. За 3 дня до окончания отправляете напоминание + новый invoice.
5. Повторяете автоматически.

Вариант 2: Чеки (createCheck) — пользователь активирует чек сам, удобно для «продления подписки одним кликом».

Вариант 3: Для закрытых каналов используйте встроенные подписки Crypto Bot (отдельный раздел в help.send.tg), но для ботов — только кастомная логика.

## 5. Получение уведомлений о платежах (Webhooks — обязательно!)

В настройках вашего App (в @CryptoBot → My Apps → ваш app → Webhooks) укажите URL вида https://yourdomain.com/crypto-webhook.

При оплате Crypto Bot делает POST на ваш URL с заголовком Crypto-Pay-Api-Signature (HMAC-SHA256 от тела + ваш токен как ключ).

Пример проверки подписи (Python):

import hmac, hashlib, json

def verify_webhook(data: bytes, signature: str, token: str) -> bool:
    expected = hmac.new(token.encode(), data, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

В теле всегда будет update_type: "invoice_paid" + полный объект Invoice (с paid_asset, paid_amount, payload и т.д.).

## 6. Полезные дополнительные методы

• getMe — проверить токен
• getBalance — текущий баланс приложения по всем активам
• getInvoices — список всех счетов (с фильтрами status=active/paid/expired)
• deleteInvoice — удалить неоплаченный счёт
• getCurrencies — актуальный список валют и минимальных сумм
• getExchangeRates — курсы
• transfer — отправить монеты пользователю (нужно включить в Security)
• createCheck / getChecks — одноразовые чеки-подарки
• getStats — статистика приложения (новинка 2024)

## 7. Комиссии и вывод средств (реальные данные 2026)

Комиссия зависит от оборота за последние 30 дней:

• 0–10 000 USD — 3%
• 10 000–50 000 — 2%
• 50 000–100 000 — 1%

• 100 000 — 0.5% или ниже (индивидуально)

Вывод на любой кошелёк TON/USDT/BTC и т.д. — мгновенно, без дополнительных комиссий Crypto Pay (только сетевые).

## 8. Промпты для ИИ (ChatGPT / Claude / Grok), чтобы подключить всё самостоятельно

Если у вас уже есть токен и кошелёк, просто скопируйте промпт:

Промпт 1 (полная интеграция на aiogram 3.x + FastAPI webhook):

Напиши полный рабочий код Telegram-бота на Python 3.11 + aiogram 3.x + FastAPI для webhook.
Использовать Crypto Pay API (токен: [ВСТАВЬ_СВОЙ]).
Функционал:
- Команда /pay — создаёт invoice на 5 USDT с payload = user_id
- Отправляет кнопку с bot_invoice_url
- Webhook /crypto_webhook проверяет подпись, при invoice_paid добавляет 30 дней подписки в SQLite
- Команда /status показывает дату окончания подписки
- Всё с обработкой ошибок, логированием, комментариями.
Использовать testnet сначала.

Промпт 2 (только backend + Flask):

Создай Flask-приложение, которое:
1. При GET /create?user=123&amount=9.99 создаёт invoice через Crypto Pay API и возвращает JSON с url.
2. Имеет endpoint /webhook, проверяет HMAC, сохраняет платеж в PostgreSQL.
Токен и URL — константы. Добавить Docker-compose.

Промпт 3 (Node.js + Telegraf):

Напиши интеграцию Crypto Pay в Telegraf-бот (Node.js). Создание инвойса, отправка кнопки, обработка webhook с верификацией подписи.

## 9. Безопасность и лучшие практики

• Включите IP-allowlist в настройках App (Security).
• Никогда не храните токен в клиентском коде.
• Для production используйте HTTPS + верификацию подписи webhook.
• Храните payload с user_id + order_id.
• Делайте резервные проверки через getInvoices раз в 5–10 минут.

## Заключение

Crypto Pay — самый простой и надёжный способ принимать крипту в Telegram-боте в 2026 году. Всё работает внутри экосистемы Telegram, без редиректов на сторонние сайты, с мгновенными уведомлениями и нулевыми комиссиями при высоком обороте.

Официальная документация (всегда актуальная):

• https://help.send.tg/ru/articles/10279948-crypto-pay-api
• https://help.crypt.bot/crypto-pay-api (зеркало)