Bots de Telegram y Stars: Guía de Acciones de Pago

Si un creador ya tiene una audiencia en Telegram, un bot puede convertir esa audiencia en acciones de pago: un informe, un archivo, un paquete de créditos, un comando privado, un mini-servicio o un desbloqueo relacionado con medios.

La parte incómoda no es el botón. Es el traspaso. El comprador necesita suficientes Stars, el bot necesita una factura limpia y la acción de pago debe desbloquearse solo después de que Telegram confirme el pago.

Esta guía es para creadores y operadores que planean una acción de pago entregada por un bot con Telegram Stars. Si tus lectores aún son nuevos con el saldo en sí, empieza con qué son las Telegram Stars. Si los compradores necesitan Stars antes del lanzamiento, envíalos a recargar Telegram Stars antes de que se active el aviso del bot.

Respuesta rápida

Una acción de pago de bot de Telegram funciona mejor cuando mantienes la oferta pequeña y verificable.

Usa este flujo:

1. Define una sola acción de pago.
2. Muestra al comprador lo que recibirá.
3. Envía una factura de Stars por esa acción.
4. Comprueba la solicitud de pre-checkout antes de aceptar el pago.
5. Entrega solo tras un evento de pago exitoso.
6. Guarda la referencia del pago para que el soporte y los reembolsos no sean adivinanzas.
7. Dile a los compradores cómo conseguir Stars antes del momento del desbloqueo.

La documentación de pagos con Stars de Telegram describe la secuencia básica de la factura para bienes y servicios digitales: sendInvoice, pre_checkout_query, answerPreCheckoutQuery, successful_payment y luego la entrega. La Bot API usa XTR como etiqueta de moneda de las Stars para estos pagos.

Esa es la columna vertebral técnica. El trabajo del creador es más sencillo: hacer la acción de pago lo bastante clara como para que el comprador sepa por qué está gastando Stars.

Qué cubre esta guía

Usa esta guía para acciones de pago entregadas por bots, como:

• desbloquear un archivo descargable;
• generar un informe privado;
• añadir créditos a una cuenta de bot;
• abrir un comando de pago;
• entregar una checklist, un paquete de prompts, un gráfico o una plantilla personalizados;
• dar acceso a un servicio puntual gestionado por un bot.

No mezcles eso con todos los flujos de Telegram Stars.

El contenido multimedia de pago es para fotos, videos y desbloqueos de medios admitidos. Si tu producto es un lanzamiento de medios, lee la guía del comprador de medios de pago de Telegram y la guía sobre cómo fijar el precio de los medios de pago de Telegram con Stars.

Las Suscripciones con Stars restringen el acceso a un canal mediante un enlace de invitación de pago con una cuota mensual. Las mini apps también pueden usar Stars, pero el flujo del comprador es distinto. Si ese es el caso, usa la guía sobre cómo pagar mini apps de Telegram con Stars.

Si primero necesitas el mapa más amplio, empieza con cómo monetizar contenido de Telegram con Stars.

Paso 1: define la acción de pago

No empieces por la factura. Empieza por lo que recibe el comprador.

Las promesas de acción de pago débiles suenan así:

• "Acceso premium."
• "Desbloquea más."
• "Apoya al bot."
• "Consigue contenido extra."

Esas frases generan preguntas de soporte porque el comprador no sabe qué cambia tras el pago.

Una promesa de acción de pago más fuerte es específica:

• "Genera un informe de auditoría privado."
• "Desbloquea el pack completo de plantillas en PDF."
• "Añade 50 créditos a tu saldo del bot."
• "Ejecuta una vez el comando avanzado de gráficos."
• "Abre la checklist privada de esta lección."

Antes de fijar cualquier precio, escribe una frase:

Tras pagar, el comprador recibe ________.

Si la frase es vaga, el flujo del bot también lo será.

Paso 2: envía la factura de Stars

Para una factura de bot estándar, el método de la Bot API de Telegram es sendInvoice. Para los pagos con Stars, la factura usa la etiqueta de moneda XTR.

Una checklist práctica para la factura:

• usa currency como XTR;
• mantén vacío el token de proveedor para los pagos con Stars donde la documentación de Telegram lo permita;
• usa un solo ítem de precio para un pago con Stars;
• pon tu referencia interna del pedido en el payload;
• mantén el título y la descripción lo bastante cortos para que el comprador reconozca la acción;
• no reutilices el mismo payload para acciones no relacionadas.

El payload importa porque la pantalla de pago no es todo tu sistema de pedidos. Tu bot todavía necesita saber a qué usuario, acción y precio corresponde esta factura.

Buenos datos del payload interno suelen incluir:

• el ID del usuario comprador;
• el ID de la acción de pago;
• el importe de Stars esperado;
• la marca de tiempo del pedido;
• un nonce o ID de pedido único;
• un estado como created, pending, paid, delivered o refunded.

Mantén humano el texto público de la factura. El comprador no debería ver IDs internos ni jerga de desarrollador.

Mal título de factura:

SKU_XTR_CMD_ADV_2026

Mejor título de factura:

Informe de gráficos avanzado

Mala descripción de factura:

Ejecutar acción de pago tras la validación del callback.

Mejor descripción de factura:

Desbloquea un informe privado de gráficos de este bot.

Paso 3: trata el pre-checkout como una barrera de seguridad

Telegram envía una solicitud de pre-checkout antes de completar el pago. Trátala como una comprobación de seguridad final, no como un trámite.

Antes de aprobar, confirma que:

• el usuario aún coincide con el pedido;
• la acción de pago aún existe;
• el importe de Stars esperado aún coincide;
• la acción aún está disponible;
• el pedido no se ha pagado ni cancelado ya;
• el payload no ha caducado.

Si algo no coincide, rechaza la solicitud de pre-checkout con un mensaje de error claro. No dejes que una factura obsoleta desbloquee la acción equivocada.

Esto es especialmente importante para bots que venden ítems limitados, accesos por tiempo o resultados generados. Un usuario puede pulsar un enlace de factura antiguo después de que la oferta haya cambiado. Tu bot debería saber qué hacer.

Paso 4: entrega solo tras el éxito

Pulsar un botón no es pagar. Una aprobación de pre-checkout no es entrega. Entrega después de que Telegram envíe el evento de pago exitoso.

Un flujo de entrega limpio se ve así:

1. Recibe successful_payment.
2. Empareja el pago con el pedido interno.
3. Guarda el ID del cargo del pago de Telegram.
4. Marca el pedido como pagado.
5. Entrega la acción de pago.
6. Marca el pedido como entregado.
7. Envía un breve mensaje de confirmación al comprador.

Si la acción de pago es instantánea, como un archivo o un paquete de créditos, la entrega puede ocurrir de inmediato tras la confirmación. Si requiere procesamiento, dile al comprador qué está pasando y qué esperar a continuación.

Mantén el soporte práctico. Si guardas el ID del pedido, la acción de pago, el importe de Stars, el ID del cargo del pago y el estado de la entrega, puedes responder la mayoría de preguntas de soporte sin rebuscar en el historial de chat.

Paso 5: haz obvio el momento de recarga del comprador

El lado del comprador es fácil de olvidar. Los creadores suelen probar el bot cuando ya tienen Stars. Los compradores reales pueden llegar con el saldo vacío.

La documentación de pagos con Stars de Telegram dice que los usuarios pueden adquirir Stars si es necesario antes de pagar bienes y servicios digitales. Eso no significa que el paso extra sea cómodo para todos los compradores. Si tu acción de pago se lanza a una hora concreta, avisa a la audiencia con antelación.

Un mensaje de lanzamiento sencillo puede decir:

El bot desbloqueará el informe de pago con Telegram Stars. Si aún no tienes suficientes Stars, recarga antes del lanzamiento para no hacerlo durante el checkout.

Aquí es donde MyStars encaja de forma natural. El creador no necesita sacar al comprador de Telegram para la acción de pago en sí. Solo necesita que los compradores tengan Stars listas antes del momento del desbloqueo. Envía a los compradores a recargar Telegram Stars antes del lanzamiento, no cuando ya están frustrados.

Si también haces lanzamientos de medios de pago, usa el plan de lanzamiento de medios de pago para programar teasers, recordatorios al comprador y la medición tras el lanzamiento.

Ramas de decisión

Si el valor de pago es un archivo o una plantilla

Mantén el pago de una sola vez. Entrega el archivo tras el pago exitoso y luego envía un breve mensaje tipo recibo.

No obligues al comprador a pedir el archivo a un administrador manualmente. Eso convierte un flujo de bot en una cola de soporte.

Si el valor de pago es un informe generado

Dile al comprador si el informe es instantáneo o queda en cola.

Si la generación puede fallar, separa la confirmación del pago del estado de la entrega:

• pagado, generando;
• pagado, entregado;
• pagado, fallido - se necesita soporte.

Eso facilita los reembolsos y el soporte.

Si el valor de pago son créditos

Añade créditos solo tras el pago exitoso. Muestra el nuevo saldo de inmediato.

Si los créditos caducan, dilo antes del checkout. Las reglas de caducidad ocultas generan quejas.

Si el valor de pago son medios

Usa el flujo correcto. Una factura de bot puede vender un bien o servicio digital, pero los medios de pago tienen su propio método de la Bot API y su comportamiento de producto. Si vendes un desbloqueo de foto/video/medios, compara el flujo con la guía del comprador de medios de pago de Telegram antes de construir.

Si el valor de pago es acceso a un canal

Eso puede ser una Suscripción con Stars u otro flujo de acceso, no una acción de bot de una sola vez. Mantén separados en tus textos el acceso mensual, las acciones de pago puntuales y los medios de pago.

Errores que evitar

• Vender una vaga promesa premium sin decir qué se desbloquea.
• Tratar la pulsación de un botón como un pago.
• Entregar tras el pre-checkout en lugar de tras el pago exitoso.
• Olvidar guardar el ID del cargo del pago de Telegram.
• Reutilizar un formato de payload para acciones no relacionadas.
• Dejar que enlaces de factura antiguos desbloqueen ofertas cambiadas.
• Ocultar la caducidad o los límites de uso hasta después del pago.
• Usar etiquetas de desarrollador en el texto de la factura visible para el comprador.
• Enviar a los compradores a recargar solo después de que el lanzamiento ya haya empezado.
• Llamar a todo flujo de Stars posts de pago, lo que puede confundir medios de pago, suscripciones, facturas de bot y contenido de canal de solo texto.

Solución de problemas

El comprador dice que pagó, pero el bot no desbloqueó

Causas probables:

• el bot no recibió ni procesó successful_payment;
• el ID del pedido interno no coincidió con el payload;
• la entrega falló tras el pago;
• el bot marcó el pedido como pagado pero no como entregado.

Solución:

• busca por ID de usuario e ID de pedido;
• revisa el ID del cargo del pago guardado;
• verifica el estado de la acción de pago;
• entrega manualmente si el pago se realizó y el ítem es válido;
• registra el fallo para que el mismo bug no se repita.

El comprador no puede pagar porque no tiene Stars

Causa probable:

• el comprador llegó al momento del pago sin suficientes Stars listas.

Solución:

• añade un recordatorio previo al lanzamiento;
• incluye un enlace para recargar Telegram Stars en las instrucciones de lanzamiento;
• mantén el mensaje de pago del bot corto y claro;
• no entierres la guía de recarga dentro de un anuncio largo.

El pre-checkout falla

Causas probables:

• el pedido caducó;
• el payload está mal formado;
• el importe esperado cambió;
• la acción de pago ya no está disponible;
• el bot ya procesó el pedido.

Solución:

• devuelve un mensaje de error claro;
• deja que el usuario cree una factura nueva;
• evita fallar en silencio sin explicación.

Llega una solicitud de reembolso o soporte

Causas probables:

• el comprador pagó por la acción equivocada;
• la entrega falló;
• el texto de la oferta no era claro;
• el comprador esperaba una suscripción o un desbloqueo de medios, pero compró una acción de bot.

Solución:

• revisa el ID del cargo del pago y el registro de entrega;
• decide si un reembolso es adecuado según tu política y los métodos disponibles de Telegram;
• reescribe la oferta si varios compradores malinterpretan el mismo punto.

Preguntas frecuentes

¿Puede un bot de Telegram cobrar Stars por una acción de pago?

Sí, la documentación de pagos con Stars de Telegram cubre bienes y servicios digitales vendidos a través de bots y mini apps. En una factura de bot, lo importante es la etiqueta de moneda XTR, el manejo del pre-checkout, la confirmación del pago exitoso y la entrega tras el pago.

¿Qué significa XTR?

XTR es la etiqueta de moneda que Telegram usa para las Stars en el flujo de pagos de la Bot API. Úsala para las facturas de Stars en lugar de tratar las Stars como un código de moneda fiat normal.

¿Las facturas de Stars necesitan un token de proveedor de pago?

La documentación de la Bot API de Telegram indica pasar un token de proveedor vacío para los pagos en Telegram Stars donde aparezca ese parámetro. Revisa la documentación vigente de la Bot API antes de implementar, porque los detalles de la API pueden cambiar.

¿Cuándo debe el bot entregar la acción?

Tras el evento de pago exitoso, no después de que el usuario pulse el botón de pagar ni únicamente tras la aprobación del pre-checkout.

¿Y si el comprador no tiene suficientes Stars?

Avisa a los compradores antes del lanzamiento. Pueden preparar su saldo primero y luego desbloquear dentro de Telegram cuando aparezca la factura del bot. Si necesitan más Stars, envíalos a recargar Telegram Stars.

¿Una acción de pago de bot es lo mismo que el contenido multimedia de pago?

No. El contenido multimedia de pago es para fotos, videos y desbloqueos de medios admitidos. Una acción de pago de bot puede ser un archivo, un informe, un paquete de créditos, un comando o un servicio entregado por el bot. Mantén el flujo y los textos separados.

¿Se pueden reembolsar los pagos con Stars?

La Bot API de Telegram incluye refundStarPayment para pagos con Stars exitosos. Guarda el ID del cargo del pago y el estado interno del pedido para gestionar el soporte y las decisiones de reembolso con claridad.

Fuentes y evidencia

• Lanzamiento de Telegram Stars: Telegram Stars: Pay for Digital Goods and More.
• Flujo de pagos con Stars para bots: Telegram Stars Payments.
• Parámetros de la factura de bot: Bot API sendInvoice.
• Alcance de los medios de pago: Bot API sendPaidMedia.
• Anuncio de Suscripciones con Stars y medios de pago: Telegram Super Channels, Star Reactions and Subscriptions.
• Términos de las Stars y alcance del saldo: Telegram Stars Terms.

Checklist final

Antes de lanzar una acción de pago de bot:

• la acción de pago es específica;
• el título de la factura es legible para humanos;
• el payload se asigna a un solo pedido interno;
• el importe de Stars se comprueba antes del pago;
• la entrega ocurre tras el pago exitoso;
• el soporte puede encontrar el ID del cargo y el estado de la entrega;
• los compradores saben cómo recargar Stars antes del aviso del bot.