Facturas de Telegram Stars (XTR) en bots: el flujo de pago para desarrolladores, paso a paso
Vender bienes digitales por Stars en un bot: sendInvoice con XTR, la respuesta a pre_checkout_query en 10 segundos, successful_payment, guardar el identificador del cargo y una lista de comprobación para el lanzamiento.
Publicado:

¿Su bot vende algo digital, como una suscripción, contenido, solicitudes de IA o artículos del juego? Entonces el pago es solo en Telegram Stars. Este artículo recorre el flujo de la factura de Telegram Stars (XTR) desde el punto de vista de un desarrollador, siguiendo la documentación oficial de la Bot API. Para saber por qué tiene que ser Stars, consulte bienes digitales en bots solo mediante Stars.
El flujo de un vistazo
| Paso | Qué hace el bot | Qué envía Telegram |
|---|---|---|
| 1 | sendInvoice con currency = XTR | — |
| 2 | Espera | pre_checkout_query |
| 3 | answerPreCheckoutQuery (en un plazo de 10 segundos) | — |
| 4 | Espera | successful_payment |
| 5 | Guarda el identificador del cargo y entrega los bienes | — |
Paso 1: crear la factura
Hay dos formas:
- Factura de bot: el método sendInvoice. Como los bienes son digitales, provider_token es una cadena vacía y el campo currency es XTR. La factura puede ir a un chat privado, un grupo o un canal.
- Factura en línea: si su bot admite el modo en línea, inputInvoiceMessageContent permite a los usuarios compartir la factura con amigos, grupos y canales. Su botón Pagar se puede usar muchas veces.
Paso 2: elegir el comportamiento de reenvío
El parámetro start_parameter lo controla:
- Factura para varios chats: las copias reenviadas conservan un botón Pagar, así que muchos usuarios pueden pagar. Las facturas en línea son siempre para varios chats.
- Factura de un solo chat: solo se puede pagar en el chat al que se envió; las copias reenviadas muestran un botón de enlace profundo al bot.
Tenga en cuenta que una factura de un solo chat enviada en el chat privado con su bot se puede pagar solo una vez. En cualquier caso, su bot siempre decide si acepta un nuevo pago.
Paso 3: comprobación previa
El usuario (comprando Stars primero si hace falta) pulsa Pagar. Su bot recibe una pre_checkout_query con los detalles del pedido y debe responder con answerPreCheckoutQuery en un plazo de 10 segundos, o la transacción se cancela. Si la rechaza, indique un motivo legible; Telegram se lo muestra al usuario.
Pasos 4–5: pago y entrega
Cuando el pago se realiza, llega un mensaje successful_payment. Solo entonces debe entregar, porque responder a pre_checkout_query no garantiza que el pago se haya completado. Guarde el telegram_payment_charge_id; lo necesitará para los reembolsos.
Antes de publicar
- Active la verificación en dos pasos para la cuenta que controla el bot.
- Proporcione las condiciones mediante /terms, y la asistencia mediante /support y /paysupport.
- Esté preparado para disputas y reembolsos con refundStarPayment. Más en reembolsos de Stars y /paysupport.
- Mantenga el servidor estable y haga copias de seguridad de los datos de pago.
Cómo probar
El entorno de pruebas dedicado de Telegram le permite probar los pagos con Stars gratis. Cuando todo funcione, pase a producción.
El lado de la compra de Stars
Sus usuarios compran Stars en la aplicación o a través de @PremiumBot, y PayStars las vende por USDT. Si su propio servicio necesita comprar Stars de forma automática, la API de PayStars y la descripción general de la API lo cubren.
Preguntas frecuentes
¿Puedo aceptar criptomonedas u otra moneda en lugar de Stars?
No. Los bienes y servicios digitales dentro de las aplicaciones de Telegram se pagan solo con Stars.
¿Cómo pruebo los pagos?
Conecte su bot al entorno de pruebas dedicado de Telegram, donde los pagos con Stars se pueden probar gratis.
¿Cómo emito un reembolso?
Con el método refundStarPayment de la Bot API.
Fuentes
Related pages
Compra Stars y Premium con USD (USDT)
Con clave API: precio de Fragment, 0 % (sitio web: 5 %).
More news
Cómo redactar una política de reembolsos para tu bot de Telegram Stars: plantilla y ejemplosQué debe cubrir una política de reembolsos para un bot de Telegram Stars: elegibilidad, plazo, /paysupport y refundStarPayment, más ejemplos de texto que puedes adaptar.Leer →
Qué ocurre con tus Telegram Stars si pierdes el acceso a tu cuentaLas Stars pertenecen a tu cuenta de Telegram, no a tu teléfono. Descubre qué ocurre con ellas si pierdes el acceso, cómo volver a entrar y cómo proteger tu saldo.Leer →
Llevar registros de los ingresos de Telegram Stars como creador o empresaCómo llevar registros claros de los ingresos de Telegram Stars: qué anotar, seguimiento de los retiros en Fragment, separación de lo personal y lo empresarial, y qué preguntar a un contador.Leer →