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

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

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

• Приём платежей - СБП и Telegram Stars

• Простая интеграция - создайте товар, получите ссылку, настройте вебхук

• Готовая инфраструктура - не нужно самостоятельно интегрировать платёжные провайдеры

• Автоматические выводы - получайте деньги в USDT

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

• Удобная оплата - покупка в один клик через Telegram

• Доступные способы оплаты - СБП, Telegram Stars

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

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

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

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

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

• Для Telegram: https://telegram.me/tribute/app?startapp=p123

• Для браузера: https://web.tribute.tg/p/123

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

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

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

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

• Оплатить напрямую Telegram Stars (если есть на балансе)

• Купить Stars через СБП и сразу обменять их на товар

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

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

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

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

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

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

1. Откройте @tribute в Telegram

2. Нажмите "Начать" и следуйте инструкциям

3. Перейдите в раздел "Дашборд автора"

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

1. В дашборде выберите "Цифровые товары" → "Создать готовый товар"

2. Вы будете перенаправлены в чат с ботом

   Отправьте боту сообщение, которое станет вашим цифровым товаром. Это может быть любое ваше сообщение - например, фотография с описанием, видео, файл или даже кружочек.

   Пример текстового сообщения для интеграции:

   ✅ Спасибо за покупку доступа к AI-ассистенту на 1 месяц!
   Доступ будет предоставлен автоматически.
   Для активации подписки вернитесь в @YourAIBot

   Важно: Именно это сообщение получит покупатель после оплаты. Добавьте инструкции для пользователя, чтобы он понимал, что делать дальше. После создания товара отредактировать это сообщение будет нельзя (но вы всегда сможете создать новый цифровой товар с другим сообщением).

3. После отправки сообщения нажмите кнопку "Создать товар" из сообщения бота

4. Заполните обязательные поля:

   • Валюта - выберите валюту для оплаты

   • Название - что увидит покупатель (например: "AI-ассистент на 1 месяц")

   • Описание - краткое описание товара

   • Цена - стоимость в выбранной валюте

5. Сохраните товар

   После сохранения вы получите уникальную ссылку для оплаты, которую можно использовать в вашей интеграции

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

1. В дашборде откройте меню (три точки) → "Настройки"

2. Перейдите в раздел "API-ключи"

3. Нажмите "Сгенерировать новый ключ"

4. Сохраните ключ в безопасном месте - он понадобится для проверки вебхуков

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

1. В разделе "API-ключи" найдите поле "URL вебхука"

2. Укажите адрес вашего сервера для приёма вебхуков:

   https://your-server.com/webhook/tribute

3. Сохраните настройки

Шаг 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://telegram.me/tribute/app?startapp=p456"
        )
    ]]
    reply_markup = InlineKeyboardMarkup(keyboard)
    
    update.message.reply_text(
        "AI-ассистент на 1 месяц - 499₽",
        reply_markup=reply_markup
    )

Работа с API

Получить товар по ID

get

Возвращает отдельный товар по его ID

Authorizations

Api-KeystringRequired

API ключ для аутентификации.

Path parameters

idintegerRequired

ID товара

Responses

200

Успешный ответ

application/json

idintegerRequired

ID товара

Example: 2548

typestring · enumRequired

Тип товара

Example: digitalPossible values:

namestringRequired

Название товара

Example: Доступ к VPN на 1 месяц

descriptionstringOptional

Описание товара

Example: Высокоскоростной VPN-сервис с неограниченным трафиком и 50+ серверами по всему миру

amountinteger · int64Required

Цена товара в минимальных единицах валюты (центах для USD/EUR, копейках для RUB). Для физических товаров это стартовая цена — берётся по самому дешёвому варианту.

Example: 499

currencystring · enumRequired

Код валюты

Example: usdPossible values:

starsAmountintegerOptional

Цена в Telegram Stars

Example: 100

starsAmountEnabledbooleanOptional

Включена ли оплата через Stars

Example: true

statusstring · enumRequired

Статус товара

Example: approvedPossible values:

isCustombooleanRequired

Является ли товар кастомным

Example: false

acceptCardsbooleanRequired

Принимается ли оплата картой

Example: true

acceptWalletPaybooleanRequired

Принимается ли оплата через кошелек

Example: false

protectContentbooleanRequired

Включена ли защита контента

Example: true

createdstring · date-timeRequired

Дата создания товара

Example: 2025-08-25T10:30:00Z

updatedstring · date-timeRequired

Дата последнего обновления товара

Example: 2025-08-25T10:30:00Z

pendingOrdersintegerOptional

Количество ожидающих заказов (для кастомных товаров)

Example: 3

imageUrlstring · uriOptional

URL изображения товара

Example: https://cdn.example.com/image.jpg

linkstring · uriRequired

Прямая ссылка на товар в приложении Telegram

Example: https://t.me/tribute_bot/app?startapp=pf6

webLinkstring · uriRequired

Веб-ссылка на товар

Example: https://web.tribute.tg/p/f6

400

Некорректный запрос (неверный формат ID товара)

application/json

401

Неавторизован (неверный API ключ)

application/json

403

Доступ запрещен

application/json

404

Товар не найден

application/json

get/products/{id}

GET /api/v1/products/{id} HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "id": 2548,
  "type": "digital",
  "name": "Доступ к VPN на 1 месяц",
  "description": "Высокоскоростной VPN-сервис с неограниченным трафиком и 50+ серверами по всему миру",
  "amount": 499,
  "currency": "usd",
  "starsAmount": 100,
  "starsAmountEnabled": true,
  "status": "approved",
  "isCustom": false,
  "acceptCards": true,
  "acceptWalletPay": false,
  "protectContent": true,
  "created": "2025-08-25T10:30:00Z",
  "updated": "2025-08-25T10:30:00Z",
  "pendingOrders": 3,
  "imageUrl": "https://cdn.example.com/image.jpg",
  "link": "https://t.me/tribute_bot/app?startapp=pf6",
  "webLink": "https://web.tribute.tg/p/f6"
}

Получить список товаров

get

Возвращает постраничный список товаров

Authorizations

Api-KeystringRequired

API ключ для аутентификации.

Query parameters

pageinteger · min: 1Optional

Номер страницы

Default: 1

sizeinteger · min: 1 · max: 100Optional

Количество элементов на странице

Default: 20

typestring · enumOptional

Фильтр по типу товара

Possible values:

descbooleanOptional

Сортировка по ID в убывающем порядке

Default: false

Responses

200

Успешный ответ

application/json

400

Некорректный запрос

application/json

401

Неавторизован (неверный API ключ)

application/json

get/products

GET /api/v1/products HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "rows": [
    {
      "id": 2548,
      "type": "digital",
      "name": "Доступ к VPN на 1 месяц",
      "description": "Высокоскоростной VPN-сервис с неограниченным трафиком и 50+ серверами по всему миру",
      "amount": 499,
      "currency": "usd",
      "starsAmount": 100,
      "starsAmountEnabled": true,
      "status": "approved",
      "isCustom": false,
      "acceptCards": true,
      "acceptWalletPay": false,
      "protectContent": true,
      "created": "2025-08-25T10:30:00Z",
      "updated": "2025-08-25T10:30:00Z",
      "pendingOrders": 3,
      "imageUrl": "https://cdn.example.com/image.jpg",
      "link": "https://t.me/tribute_bot/app?startapp=pf6",
      "webLink": "https://web.tribute.tg/p/f6"
    }
  ],
  "meta": {
    "total": 1,
    "offset": 1,
    "limit": 1
  }
}

Отменить покупку цифрового товара

post

Отменяет покупку цифрового товара и выполняет возврат платежа.

Важно: Этот эндпоинт поддерживает возврат только для покупок, оплаченных Telegram Stars. Покупки, оплаченные другими способами, не могут быть возвращены через этот эндпоинт.

Authorizations

Api-KeystringRequired

API ключ для аутентификации.

Path parameters

purchaseIdintegerRequired

ID покупки цифрового товара (ProductPurchase.ID)

Example: 12345

Responses

200

Покупка успешно отменена, платёж возвращён

application/json

successbooleanRequired

Статус успешности операции

Example: true

purchaseIdintegerRequired

ID отменённой покупки

Example: 12345

messagestringRequired

Сообщение об успехе

Example: purchase cancelled and payment refunded

400

Некорректный запрос

application/json

401

Неавторизован (неверный API ключ)

application/json

403

Доступ запрещён (не владелец товара)

application/json

404

Покупка или пользователь не найден

application/json

500

Внутренняя ошибка сервера

application/json

post/products/purchases/{purchaseId}/cancel

POST /api/v1/products/purchases/{purchaseId}/cancel HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "purchaseId": 12345,
  "message": "purchase cancelled and payment refunded"
}

Покупка цифрового товара

Уведомление о покупке цифрового товара

Payload

namestring · enumRequiredExample: new_digital_productPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

statusstringOptionalExample: ok

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "new_digital_product",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "product_id": 456,
    "product_name": "VPN Доступ - 1 месяц",
    "amount": 500,
    "currency": "usd",
    "trb_user_id": "T-31326",
    "telegram_user_id": 12321321,
    "telegram_username": "durov",
    "purchase_id": 78901,
    "transaction_id": 234567,
    "purchase_created_at": "2025-03-20T01:15:58.33246Z"
  }
}

Цифровой товар возвращён

Уведомление о возврате цифрового товара. Этот вебхук срабатывает когда:

• Пользователь возвращает Stars через App Store, Google Play или банк
• Автор инициирует возврат через API

Важно: Используйте purchase_id для сопоставления возвратов с оригинальными покупками и отзыва доступа к цифровому контенту.

Payload

namestring · enumRequiredExample: digital_product_refundedPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

statusstringOptionalExample: ok

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "digital_product_refunded",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "product_id": 456,
    "product_name": "VPN Доступ - 1 месяц",
    "amount": 500,
    "currency": "usd",
    "trb_user_id": "T-31326",
    "telegram_user_id": 12321321,
    "telegram_username": "durov",
    "purchase_id": 78901,
    "transaction_id": 234567,
    "refund_reason": "telegram_refund",
    "refunded_at": "2025-03-20T02:30:00.33246Z"
  }
}

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

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

1. AI-ассистент - 1 месяц (ID: 456) - 499₽

2. AI-ассистент - 3 месяца (ID: 457) - 1299₽

3. AI-ассистент - 1 год (ID: 458) - 3999₽

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

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

• 5 минут

• 15 минут

• 30 минут

• 1 час

• 10 часов

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

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

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

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

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

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

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

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

---