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

Преимущества интеграции цифровых товаров 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

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

get

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

Authorizations

Api-KeystringRequired

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

Path parameters

idintegerRequired

ID товара

Responses

200

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

application/json

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

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

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",
    "user_id": 31326,
    "telegram_user_id": 12321321,
    "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

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",
    "user_id": 31326,
    "telegram_user_id": 12321321,
    "purchase_id": 78901,
    "transaction_id": 234567,
    "refund_reason": "telegram_refund",
    "refunded_at": "2025-03-20T02:30:00.33246Z"
  }
}

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

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

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Статистика в сервисе Tribute

Last updated 3 days ago

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

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

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

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

hashtag1. Вы создаёте цифровой товарarrow-up-right в Tribute

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

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

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

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

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

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

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

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

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

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

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

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

hashtagРабота с API

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

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

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

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

Payload

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

Payload

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Работа с API

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

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

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

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

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

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

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

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

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