Интеграция цифровых товаров в свой продукт

Эта инструкция предназначена для владельцев Telegram-ботов и сервисов, которые хотят использовать Tribute как платёжную систему. Принимайте платежи через СБП и Telegram Stars, получайте выводы в USDT

Преимущества интеграции цифровых товаров Tribute

Для вас как владельца сервиса:

Приём платежей - СБП и Telegram Stars
Простая интеграция - создайте товар, получите ссылку, настройте вебхук
Готовая инфраструктура - не нужно самостоятельно интегрировать платёжные провайдеры
Автоматические выводы - получайте деньги в USDT

Для ваших пользователей:

Удобная оплата - покупка в один клик через Telegram
Доступные способы оплаты - СБП, Telegram Stars

Как это работает: общая схема

1. Вы создаёте цифровой товар в Tribute

Например, для AI-ассистента это может быть "Доступ к AI-ассистенту на 1 месяц"

2. Получаете уникальную ссылку на оплату

Каждый товар имеет свою ссылку вида:

Для Telegram: https://t.me/tribute/app?startapp=p123
Для браузера: https://web.tribute.tg/p/123

3. Направляете пользователей на эту ссылку

В вашем боте или другом сервисе добавляете кнопку "Оплатить", которая ведёт на ссылку товара

4. Пользователь оплачивает

Покупатель может:

Оплатить напрямую Telegram Stars (если есть на балансе)
Купить Stars через СБП и сразу обменять их на товар

5. Вы получаете вебхук об успешной оплате

После оплаты на ваш сервер приходит POST-запрос с информацией о покупке. Подробнее о формате вебхуков в документации по вебхукам

6. Предоставляете доступ пользователю

По Telegram ID из вебхука активируете услугу для пользователя

Пошаговая инструкция по настройке

Шаг 1: Регистрация в Tribute

Откройте @tribute в Telegram
Нажмите "Начать" и следуйте инструкциям
Перейдите в раздел "Дашборд автора"

Шаг 2: Создание цифрового товара

В дашборде выберите "Цифровые товары" → "Создать готовый товар"
Вы будете перенаправлены в чат с ботом
Отправьте боту сообщение, которое станет вашим цифровым товаром. Это может быть любое ваше сообщение - например, фотография с описанием, видео, файл или даже кружочек.
Пример текстового сообщения для интеграции:
```
✅ Спасибо за покупку доступа к AI-ассистенту на 1 месяц!
Доступ будет предоставлен автоматически.
Для активации подписки вернитесь в @YourAIBot
```
Важно: Именно это сообщение получит покупатель после оплаты. Добавьте инструкции для пользователя, чтобы он понимал, что делать дальше. После создания товара отредактировать это сообщение будет нельзя (но вы всегда сможете создать новый цифровой товар с другим сообщением).
После отправки сообщения нажмите кнопку "Создать товар" из сообщения бота
Заполните обязательные поля:
- Валюта - выберите валюту для оплаты
- Название - что увидит покупатель (например: "AI-ассистент на 1 месяц")
- Описание - краткое описание товара
- Цена - стоимость в выбранной валюте
Сохраните товар
После сохранения вы получите уникальную ссылку для оплаты, которую можно использовать в вашей интеграции

Шаг 3: Получение API-ключа

В дашборде откройте меню (три точки) → "Настройки"
Перейдите в раздел "API-ключи"
Нажмите "Сгенерировать новый ключ"
Сохраните ключ в безопасном месте - он понадобится для проверки вебхуков

Шаг 4: Настройка вебхуков

В разделе "API-ключи" найдите поле "URL вебхука"
Укажите адрес вашего сервера для приёма вебхуков:
```
https://your-server.com/webhook/tribute
```
Сохраните настройки

Шаг 5: Обработка вебхуков на вашем сервере

После успешной оплаты цифрового товара Tribute отправит POST-запрос на ваш URL:

Формат вебхука

{
  "name": "new_digital_product",
  "created_at": "2025-03-20T01:15:58.332Z",
  "sent_at": "2025-03-20T01:15:58.542Z",
  "payload": {
    "product_id": 456,
    "amount": 500,
    "currency": "usd",
    "user_id": 31326,
    "telegram_user_id": 12321321
  }
}

Проверка подписи вебхука

Каждый запрос содержит заголовок trbt-signature с HMAC-SHA256 подписью тела запроса. Примеры проверки подписи и обработки вебхуков доступны в документации по вебхукам

Шаг 6: Интеграция в вашего бота

В вашем Telegram-боте добавьте кнопку оплаты

Пример кода на Python

# Python + python-telegram-bot
from telegram import InlineKeyboardButton, InlineKeyboardMarkup

def send_payment_button(update, context):
    keyboard = [[
        InlineKeyboardButton(
            "💳 Оплатить (499₽)",
            url="https://t.me/tribute/app?startapp=p456"
        )
    ]]
    reply_markup = InlineKeyboardMarkup(keyboard)
    
    update.message.reply_text(
        "AI-ассистент на 1 месяц - 499₽",
        reply_markup=reply_markup
    )

Работа с API

Получение информации о товаре

GET https://tribute.tg/api/v1/products/456
Headers:
  X-Api-Key: YOUR_API_KEY

JSON ответ

{
  "id": 456,
  "type": "digital",
  "name": "AI-ассистент на 1 месяц",
  "amount": 499,
  "currency": "rub",
  "starsAmount": 100,
  "link": "https://t.me/tribute/app?startapp=p456",
  "webLink": "https://web.tribute.tg/p/456"
}

Получение списка всех ваших товаров

GET https://tribute.tg/api/v1/products?type=digital
Headers:
  X-Api-Key: YOUR_API_KEY

Создание разных тарифов

Для разных тарифов создайте несколько цифровых товаров:

AI-ассистент - 1 месяц (ID: 456) - 499₽
AI-ассистент - 3 месяца (ID: 457) - 1299₽
AI-ассистент - 1 год (ID: 458) - 3999₽

Обработка повторных попыток

При ошибке доставки вебхука Tribute повторяет попытки через:

5 минут
15 минут
30 минут
1 час
10 часов

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

Выводы средств

Заработанные средства вы можете выводить в USDT (вывод на банковские карты будет добавлен в будущем). Настройте автоматические выводы в разделе "Кошелек".

Часто задаваемые вопросы

Как быстро приходят вебхуки?

Обычно в течение 1-2 секунд после успешной оплаты.

Можно ли отменить платёж?

Цифровой товар можно отменить через поддержку Tribute.

PreviousКак настроить веб-оплату цифровых товаров NextСтатистика

Last updated 10 days ago