Integrando produtos digitais ao seu produto

Este guia é para proprietários de bots e serviços do Telegram que desejam usar o Tribute como sistema de pagamento. Aceite pagamentos via SBP e Telegram Stars, receba saques em USDT sem um provedor de pagamentos complexo

Benefícios da integração dos Produtos Digitais do Tribute

Para você, como dono do serviço:

• Aceitação de pagamentos - SBP e Telegram Stars

• Integração simples - crie um produto, obtenha um link, configure um webhook

• Infraestrutura pronta - não é necessário integrar provedores de pagamento por conta própria

• Saques automáticos - receba dinheiro em USDT

Para seus usuários:

• Pagamento conveniente - compra com um clique pelo Telegram

• Métodos de pagamento disponíveis - SBP, Telegram Stars

Como funciona: esquema geral

1. Você cria um produto digital no Tribute

Por exemplo, para um assistente de IA, poderia ser "Acesso ao Assistente de IA por 1 mês"

2. Obtenha um link de pagamento exclusivo

Cada produto tem seu próprio link no formato:

• Para o Telegram: https://telegram.me/tribute/app?startapp=p123

• Para o navegador: https://web.tribute.tg/p/123

3. Direcione os usuários para este link

No seu bot ou outro serviço, adicione um botão "Pagar" que leve ao link do produto

4. O usuário paga

O comprador pode:

• Pagar diretamente com Telegram Stars (se houver saldo disponível)

• Comprar Stars via SBP e trocá-las imediatamente pelo produto

5. Você recebe um webhook sobre o pagamento realizado com sucesso

Após o pagamento, uma solicitação POST com as informações da compra chega ao seu servidor. Mais sobre o formato do webhook na documentação de webhooks

6. Forneça acesso ao usuário

Ative o serviço para o usuário usando o ID do Telegram do webhook

Instruções de configuração passo a passo

Etapa 1: Registro no Tribute

1. Abra @tribute no Telegram

2. Clique em "Start" e siga as instruções

3. Vá para a seção "Painel do Autor"

Etapa 2: Criação de um produto digital

1. No painel, selecione "Produtos Digitais" → "Criar produto instantâneo"

2. Você será redirecionado para o chat do bot

   Envie ao bot uma mensagem que se tornará seu produto digital. Pode ser qualquer mensagem - por exemplo, uma foto com descrição, vídeo, arquivo ou até mesmo uma mensagem de voz.

   Mensagem de exemplo para integração:

   ✅ Obrigado por comprar o acesso ao Assistente de IA por 1 mês!
   O acesso será fornecido automaticamente.
   Para ativar sua assinatura, volte para @YourAIBot

   Importante: Esta é a mensagem exata que o comprador receberá após o pagamento. Adicione instruções para o usuário para que ele entenda o que fazer em seguida. Depois que o produto for criado, esta mensagem não poderá ser editada (mas você sempre pode criar um novo produto digital com uma mensagem diferente).

3. Depois de enviar a mensagem, clique no botão "Criar Produto" na mensagem do bot

4. Preencha os campos obrigatórios:

   • Moeda - escolha a moeda de pagamento

   • Nome - o que o comprador verá (por exemplo: "Assistente de IA por 1 mês")

   • Descrição - breve descrição do produto

   • Preço - custo na moeda selecionada

5. Salve o produto

   Após salvar, você receberá um link de pagamento exclusivo que pode ser usado na sua integração

Etapa 3: Obtenção da chave de API

1. No painel, abra o menu (três pontos) → "Configurações"

2. Vá para a seção "Chaves de API"

3. Clique em "Gerar Nova Chave"

4. Guarde a chave em um local seguro - você precisará dela para verificar webhooks

Etapa 4: Configuração de webhooks

1. Na seção "Chaves de API", encontre o campo "Webhook URL"

2. Especifique o endereço do seu servidor para receber webhooks:

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

3. Salve as configurações

Etapa 5: Processamento de webhooks no seu servidor

Após o pagamento bem-sucedido de um produto digital, o Tribute enviará uma solicitação POST para a sua URL:

Formato do webhook

{
  "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
  }
}

Verificação da assinatura do webhook

Cada solicitação contém um trbt-signature cabeçalho com a assinatura HMAC-SHA256 do corpo da solicitação. Exemplos de verificação de assinatura e processamento de webhook estão disponíveis na documentação de webhooks

Etapa 6: Integração ao seu bot

No seu bot do Telegram, adicione um botão de pagamento

Código Python

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

def send_payment_button(update, context):
    keyboard = [[
        InlineKeyboardButton(
            "💳 Pagar ($9.99)",
            url="https://telegram.me/tribute/app?startapp=p456"
        )
    ]]
    reply_markup = InlineKeyboardMarkup(keyboard)
    
    update.message.reply_text(
        "Assistente de IA por 1 mês - $9.99",
        reply_markup=reply_markup
    )

Trabalhando com a API

Get Product by ID

get

Returns a single product by its ID

Autorizações

Api-KeystringObrigatório

API key for authentication.

Parâmetros de rota

idintegerObrigatório

Product ID

Respostas

200

Successful response

application/json

idintegerObrigatório

Product ID

Example: 2548

typestring · enumObrigatório

Product type

Example: digitalValores possíveis:

namestringObrigatório

Product name

Example: VPN Access - 1 Month

descriptionstringOpcional

Product description

Example: High-speed VPN service with unlimited bandwidth and 50+ server locations worldwide

amountinteger · int64Obrigatório

Product price in smallest currency units (cents for USD/EUR, kopecks for RUB). For physical products this is the starting price, taken from the cheapest variant.

Example: 499

currencystring · enumObrigatório

Currency code

Example: usdValores possíveis:

starsAmountintegerOpcional

Price in Telegram Stars

Example: 100

starsAmountEnabledbooleanOpcional

Whether payment with Stars is enabled

Example: true

statusstring · enumObrigatório

Product status

Example: approvedValores possíveis:

isCustombooleanObrigatório

Whether this is a custom product

Example: false

acceptCardsbooleanObrigatório

Whether card payments are accepted

Example: true

acceptWalletPaybooleanObrigatório

Whether wallet payments are accepted

Example: false

protectContentbooleanObrigatório

Whether content protection is enabled

Example: true

createdstring · date-timeObrigatório

Product creation date

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

updatedstring · date-timeObrigatório

Product last update date

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

pendingOrdersintegerOpcional

Number of pending orders (for custom products)

Example: 3

imageUrlstring · uriOpcional

Product image URL

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

linkstring · uriObrigatório

Direct link to product in Telegram app

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

webLinkstring · uriObrigatório

Web link to product

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

400

Bad request (invalid product ID format)

application/json

401

Unauthorized (invalid API key)

application/json

403

Access denied

application/json

404

Product not found

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 Access - 1 Month",
  "description": "High-speed VPN service with unlimited bandwidth and 50+ server locations worldwide",
  "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 Products List

get

Returns a paginated list of products

Autorizações

Api-KeystringObrigatório

API key for authentication.

Parâmetros de consulta

pageinteger · mín: 1Opcional

Page number

Default: 1

sizeinteger · mín: 1 · máx: 100Opcional

Items per page

Default: 20

typestring · enumOpcional

Filter by product type

Valores possíveis:

descbooleanOpcional

Sort by ID descending

Default: false

Respostas

200

Successful response

application/json

400

Bad request

application/json

401

Unauthorized (invalid API key)

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 Access - 1 Month",
      "description": "High-speed VPN service with unlimited bandwidth and 50+ server locations worldwide",
      "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
  }
}

Cancel Digital Product Purchase

post

Cancels a digital product purchase and refunds the payment.

Important: This endpoint only supports refunds for purchases paid with Telegram Stars. Purchases paid with other payment methods cannot be refunded via this endpoint.

Autorizações

Api-KeystringObrigatório

API key for authentication.

Parâmetros de rota

purchaseIdintegerObrigatório

Digital product purchase ID (ProductPurchase.ID)

Example: 12345

Respostas

200

Purchase successfully cancelled and payment refunded

application/json

successbooleanObrigatório

Operation success status

Example: true

purchaseIdintegerObrigatório

Cancelled purchase ID

Example: 12345

messagestringObrigatório

Success message

Example: purchase cancelled and payment refunded

400

Bad request

application/json

401

Unauthorized (invalid API key)

application/json

403

Access denied (not the product owner)

application/json

404

Purchase or user not found

application/json

500

Internal server error

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"
}

New Digital Product Purchase

Notification about a digital product purchase

Carga útil

namestring · enumObrigatórioExample: new_digital_productValores possíveis:

created_atstring · date-timeObrigatório

Event creation time

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

sent_atstring · date-timeObrigatório

Event sending time

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

Respostas

200

Webhook successfully processed

application/json

statusstringOpcionalExample: ok

400

Invalid webhook data

401

Invalid webhook signature

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 Access - 1 Month",
    "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"
  }
}

Digital Product Refunded

Notification about a digital product refund. This webhook is triggered when:

• A user refunds Stars through App Store, Google Play, or their bank
• A creator initiates a refund via the API

Important: Use purchase_id to match refunds with original purchases and revoke access to digital content.

Carga útil

namestring · enumObrigatórioExample: digital_product_refundedValores possíveis:

created_atstring · date-timeObrigatório

Event creation time

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

sent_atstring · date-timeObrigatório

Event sending time

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

Respostas

200

Webhook successfully processed

application/json

statusstringOpcionalExample: ok

400

Invalid webhook data

401

Invalid webhook signature

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 Access - 1 Month",
    "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"
  }
}

Criando diferentes tarifas

Para diferentes níveis, crie vários produtos digitais:

1. Assistente de IA - 1 mês (ID: 456) - $9.99

2. Assistente de IA - 3 meses (ID: 457) - $24.99

3. Assistente de IA - 1 ano (ID: 458) - $79.99

Tratamento de tentativas de reenvio

Quando a entrega do webhook falhar, o Tribute tentará novamente após:

• 5 minutos

• 15 minutos

• 30 minutos

• 1 hora

• 10 horas

Certifique-se de que seu handler seja idempotente (reprocessar o mesmo pagamento não criará duplicatas).

Saques

Você pode sacar os fundos ganhos em USDT (saques para cartão bancário serão adicionados no futuro). Configure saques automáticos na seção "Carteira".

Perguntas frequentes

Com que rapidez os webhooks chegam?

Normalmente em 1-2 segundos após o pagamento bem-sucedido.

Posso cancelar um pagamento?

Produtos digitais podem ser cancelados pelo suporte do Tribute.

---