Integración de productos digitales en tu producto

Esta guía está pensada para propietarios de bots y servicios de Telegram que quieran usar Tribute como sistema de pago. Acepta pagos mediante SBP y Telegram Stars, recibe retiros en USDT sin un proveedor de pagos complejo

Beneficios de la integración de productos digitales de Tribute

Para ti, como propietario del servicio:

• Aceptación de pagos - SBP y Telegram Stars

• Integración sencilla - crea un producto, obtén un enlace, configura un webhook

• Infraestructura lista - no necesitas integrar tú mismo a los proveedores de pago

• Retiradas automáticas - recibe dinero en USDT

Para tus usuarios:

• Pago conveniente - compra con un clic a través de Telegram

• Métodos de pago disponibles - SBP, Telegram Stars

Cómo funciona: esquema general

1. Tú creas un producto digital en Tribute

Por ejemplo, para un asistente de IA podría ser "Acceso al asistente de IA durante 1 mes"

2. Obtén un enlace de pago único

Cada producto tiene su propio enlace en el formato:

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

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

3. Dirige a los usuarios a este enlace

En tu bot u otro servicio, añade un botón "Pagar" que lleve al enlace del producto

4. El usuario paga

El comprador puede:

• Pagar directamente con Telegram Stars (si hay saldo disponible)

• Comprar Stars vía SBP e intercambiarlas inmediatamente por el producto

5. Recibes un webhook sobre el pago exitoso

Después del pago, llega a tu servidor una solicitud POST con la información de la compra. Más sobre el formato del webhook en la documentación de webhooks

6. Proporciona acceso al usuario

Activa el servicio para el usuario usando el ID de Telegram del webhook

Instrucciones de configuración paso a paso

Paso 1: Registro en Tribute

1. Abre @tribute en Telegram

2. Haz clic en "Start" y sigue las instrucciones

3. Ve a la sección "Author Dashboard"

Paso 2: Creación de un producto digital

1. En el panel, selecciona "Digital Products" → "Create instant product"

2. Serás redirigido al chat del bot

   Envía al bot un mensaje que se convertirá en tu producto digital. Puede ser cualquier mensaje: por ejemplo, una foto con descripción, un video, un archivo o incluso una nota de voz.

   Texto de ejemplo para la integración:

   ✅ ¡Gracias por comprar acceso al asistente de IA durante 1 mes!
   El acceso se proporcionará automáticamente.
   Para activar tu suscripción, vuelve a @YourAIBot

   Importante: Este es el mensaje exacto que recibirá el comprador después del pago. Añade instrucciones para el usuario para que entienda qué hacer a continuación. Una vez creado el producto, este mensaje no se puede editar (pero siempre puedes crear un nuevo producto digital con un mensaje diferente).

3. Después de enviar el mensaje, haz clic en el botón "Create Product" del mensaje del bot

4. Completa los campos obligatorios:

   • Moneda - elige la moneda de pago

   • Nombre - lo que verá el comprador (por ejemplo: "Asistente de IA durante 1 mes")

   • Descripción - breve descripción del producto

   • Precio - coste en la moneda seleccionada

5. Guarda el producto

   Después de guardar, recibirás un enlace de pago único que se puede usar en tu integración

Paso 3: Obtención de la clave API

1. En el panel, abre el menú (tres puntos) → "Settings"

2. Ve a la sección "API Keys"

3. Haz clic en "Generate New Key"

4. Guarda la clave en un lugar seguro: la necesitarás para verificar los webhooks

Paso 4: Configuración de webhooks

1. En la sección "API Keys", busca el campo "Webhook URL"

2. Especifica la dirección de tu servidor para recibir webhooks:

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

3. Guardar configuración

Paso 5: Procesamiento de webhooks en tu servidor

Después de un pago exitoso de un producto digital, Tribute enviará una solicitud POST a tu URL:

Formato del 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
  }
}

Verificación de la firma del webhook

Cada solicitud contiene un trbt-signature encabezado con la firma HMAC-SHA256 del cuerpo de la solicitud. Los ejemplos de verificación de firma y procesamiento de webhooks están disponibles en la documentación de webhooks

Paso 6: Integración en tu bot

En tu bot de Telegram, añade un botón de pago

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(
        "Asistente de IA durante 1 mes - $9.99",
        reply_markup=reply_markup
    )

Trabajando con la API

Get Product by ID

get

Returns a single product by its ID

Autorizaciones

Api-KeystringRequerido

API key for authentication.

Parámetros de ruta

idintegerRequerido

Product ID

Respuestas

200

Successful response

application/json

idintegerRequerido

Product ID

Example: 2548

typestring · enumRequerido

Product type

Example: digitalValores posibles:

namestringRequerido

Product name

Example: VPN Access - 1 Month

descriptionstringOpcional

Product description

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

amountinteger · int64Requerido

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 · enumRequerido

Currency code

Example: usdValores posibles:

starsAmountintegerOpcional

Price in Telegram Stars

Example: 100

starsAmountEnabledbooleanOpcional

Whether payment with Stars is enabled

Example: true

statusstring · enumRequerido

Product status

Example: approvedValores posibles:

isCustombooleanRequerido

Whether this is a custom product

Example: false

acceptCardsbooleanRequerido

Whether card payments are accepted

Example: true

acceptWalletPaybooleanRequerido

Whether wallet payments are accepted

Example: false

protectContentbooleanRequerido

Whether content protection is enabled

Example: true

createdstring · date-timeRequerido

Product creation date

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

updatedstring · date-timeRequerido

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 · uriRequerido

Direct link to product in Telegram app

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

webLinkstring · uriRequerido

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

Autorizaciones

Api-KeystringRequerido

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 posibles:

descbooleanOpcional

Sort by ID descending

Default: false

Respuestas

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.

Autorizaciones

Api-KeystringRequerido

API key for authentication.

Parámetros de ruta

purchaseIdintegerRequerido

Digital product purchase ID (ProductPurchase.ID)

Example: 12345

Respuestas

200

Purchase successfully cancelled and payment refunded

application/json

successbooleanRequerido

Operation success status

Example: true

purchaseIdintegerRequerido

Cancelled purchase ID

Example: 12345

messagestringRequerido

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 · enumRequeridoExample: new_digital_productValores posibles:

created_atstring · date-timeRequerido

Event creation time

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

sent_atstring · date-timeRequerido

Event sending time

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

Respuestas

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 · enumRequeridoExample: digital_product_refundedValores posibles:

created_atstring · date-timeRequerido

Event creation time

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

sent_atstring · date-timeRequerido

Event sending time

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

Respuestas

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

Creación de diferentes tarifas

Para diferentes niveles, crea varios productos digitales:

1. Asistente de IA - 1 mes (ID: 456) - $9.99

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

3. Asistente de IA - 1 año (ID: 458) - $79.99

Gestión de reintentos

Cuando falla la entrega del webhook, Tribute reintenta después de:

• 5 minutos

• 15 minutos

• 30 minutos

• 1 hora

• 10 horas

Asegúrate de que tu controlador sea idempotente (reprocesar el mismo pago no creará duplicados).

Retiradas

Puedes retirar los fondos ganados en USDT (las retiradas a tarjeta bancaria se añadirán en el futuro). Configura las retiradas automáticas en la sección "Wallet".

Preguntas frecuentes

¿Con qué rapidez llegan los webhooks?

Normalmente en 1-2 segundos después de un pago exitoso.

¿Puedo cancelar un pago?

Los productos digitales pueden cancelarse a través del soporte de Tribute.

---