Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Integración de productos digitales en tu producto

Esta guía es para propietarios de bots y servicios de Telegram que desean usar Tribute como sistema de pago. Acepte pagos a través de SBP y Telegram Stars, reciba 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:

    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:

  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

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

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
get/products/{id}

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
get/products

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
post/products/purchases/{purchaseId}/cancel

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

Payload

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

Payload

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.

AnteriorCómo configurar el pago web para productos digitalesSiguienteEstadísticas

Última actualización