Pagos con Telegram Stars en bots: facturas, pre-checkout, reembolsos y suscripciones
Para aceptar pagos con Telegram Stars en un bot, envía una factura con sendInvoice usando la moneda XTR y un provider_token vacío, responde la actualización pre_checkout_query con answerPreCheckoutQuery en menos de 10 segundos y entrega el producto solo cuando llegue un mensaje con successful_payment. Telegram Stars es la moneda obligatoria para los bienes y servicios digitales que se venden en las apps de Telegram. Esta guía recorre el flujo completo con un bot funcional en Python y JavaScript, y luego cubre reembolsos, historial de transacciones, suscripciones y contenido de pago.
Cómo funcionan los pagos con Telegram Stars en un bot
Telegram Stars es un artículo virtual dentro de la app. Los usuarios las compran mediante compras in-app de Apple o Google, o a través de @PremiumBot, y las gastan en tu bot; el formulario de pago no pide datos personales. El flujo:
- El bot envía una factura:
sendInvoicea un chat ocreateInvoiceLinkpara obtener un enlace. - El usuario pulsa Pagar (y compra Stars antes, si le faltan).
- El bot recibe una actualización con
pre_checkout_query. - El bot confirma o rechaza el pedido con
answerPreCheckoutQueryen menos de 10 segundos. - Telegram envía un mensaje de servicio con
successful_payment. - El bot guarda
telegram_payment_charge_idy entrega el producto.
Los bienes digitales se venden en Stars. Telegram establece que un bot o una Mini App debe usar Telegram Stars para vender bienes y servicios digitales dentro de las apps de Telegram, sin importar el sitio web o el proveedor de pagos que uses fuera; de lo contrario, Telegram no puede mostrar tu bot a los usuarios de móvil. Las otras monedas y proveedores son solo para bienes físicos, que usan un flujo aparte con provider token.
Enviar una factura con sendInvoice y XTR
Una factura mínima en Stars por 50 Stars:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendInvoice" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"title": "Paquete Pro",
"description": "50 generaciones de imágenes extra para tu cuenta",
"payload": "pro-pack-v1",
"provider_token": "",
"currency": "XTR",
"prices": [{"label": "Paquete Pro", "amount": 50}]
}'
El método devuelve el Message enviado. Los parámetros que importan para Stars:
| Parámetro | Regla para Telegram Stars |
|---|---|
title | Nombre del producto, de 1 a 32 caracteres. |
description | Descripción del producto, de 1 a 255 caracteres. |
payload | De 1 a 128 bytes, no se muestra al usuario. Pon aquí el id del pedido o del producto; vuelve en el pre-checkout y en el pago. |
provider_token | Opcional; para Stars pasa una cadena vacía. |
currency | XTR. |
prices | Arreglo de LabeledPrice que debe tener exactamente un elemento; amount es el precio en Stars (un entero). |
start_parameter | Vacío: las copias reenviadas conservan el botón Pagar. Con valor: las copias reenviadas muestran en su lugar un botón URL con un deep link al bot. |
photo_url | Imagen opcional del producto, con photo_size, photo_width y photo_height. |
Las propinas (max_tip_amount) no se admiten con Stars, y need_name, need_email, need_shipping_address, is_flexible y campos parecidos se ignoran. Si agregas tu propio reply_markup, el primer botón debe ser de pago ("pay": true); las subcadenas ⭐ y XTR en su texto se reemplazan por el ícono de Star. Las facturas pueden ir a chats privados, grupos y canales. Pruébalo sin código: abre sendInvoice en Bot API Tester, completa los campos de arriba y envíate una factura.
createInvoiceLink para Mini Apps y sitios web
createInvoiceLink recibe los mismos title, description, payload, currency y prices, pero en vez de enviar un mensaje devuelve un enlace de factura como cadena. Ábrelo desde una Mini App con Telegram.WebApp.openInvoice(url) o compártelo como un enlace normal. También es el método para las suscripciones (ver más abajo).
Responder pre_checkout_query en menos de 10 segundos
Cuando el usuario pulsa Pagar, el bot recibe un PreCheckoutQuery con id, from, currency, total_amount e invoice_payload. Debes responder en menos de 10 segundos o la transacción se cancela:
ok: truesi el producto está disponible y puedes cumplir el pedido.ok: falsemáserror_message, un motivo legible que Telegram muestra al usuario, por ejemplo «Esta oferta expiró, envía /buy para recibir una factura nueva».
Mantén este handler rápido: valida el payload y el stock, responde y deja todo lo demás para después. Aprobar la consulta no significa que el dinero ya llegó.
Entregar después de successful_payment
Un pago exitoso llega como un message cuyo campo successful_payment contiene currency, total_amount, invoice_payload y telegram_payment_charge_id. La regla de Telegram es clara: verifica siempre que recibiste successful_payment antes de entregar. Guarda telegram_payment_charge_id junto con el user id del comprador, porque un reembolso requiere ambos.
Ejemplo completo: un bot que vende por Telegram Stars
Este bot con long polling envía una factura con /buy, valida el pre-checkout, registra el pago y responde a /paysupport. Fíjate en allowed_updates: si restringes los tipos de actualización, incluye pre_checkout_query, o los pagos nunca llegarán al bot.
import json
import os
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
PAYLOAD = "pro-pack-v1"
PRICE = 50 # en Telegram Stars
def call(method, **params):
data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
if not data["ok"]:
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
return data["result"]
def handle(update):
query = update.get("pre_checkout_query")
if query:
ok = (query["invoice_payload"] == PAYLOAD and query["currency"] == "XTR"
and query["total_amount"] == PRICE)
answer = {"pre_checkout_query_id": query["id"], "ok": ok}
if not ok:
answer["error_message"] = "Esta oferta expiró. Envía /buy para recibir una factura nueva."
call("answerPreCheckoutQuery", **answer) # en menos de 10 segundos
return
msg = update.get("message")
if not msg:
return
chat_id = msg["chat"]["id"]
if "successful_payment" in msg:
payment = msg["successful_payment"]
with open("payments.jsonl", "a") as f: # guarda el charge id para reembolsos
f.write(json.dumps({"user_id": msg["from"]["id"],
"charge_id": payment["telegram_payment_charge_id"],
"payload": payment["invoice_payload"],
"amount": payment["total_amount"]}) + "\n")
call("sendMessage", chat_id=chat_id, text="¡Gracias! Tu Paquete Pro ya está activo.")
elif msg.get("text") == "/buy":
call("sendInvoice", chat_id=chat_id, title="Paquete Pro",
description="50 generaciones de imágenes extra para tu cuenta",
payload=PAYLOAD, provider_token="", currency="XTR",
prices=[{"label": "Paquete Pro", "amount": PRICE}])
elif msg.get("text") == "/paysupport":
call("sendMessage", chat_id=chat_id,
text="¿Problemas con un pago? Descríbelo en un solo mensaje y te responderemos en 24 horas.")
offset = 0
while True:
updates = call("getUpdates", offset=offset, timeout=30,
allowed_updates=["message", "pre_checkout_query"])
for update in updates:
offset = update["update_id"] + 1
handle(update)import { appendFile } from "node:fs/promises";
const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const PAYLOAD = "pro-pack-v1";
const PRICE = 50; // en Telegram Stars
async function call(method, params = {}) {
const res = await fetch(`${API}/${method}`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(params),
signal: AbortSignal.timeout(40_000),
});
const data = await res.json();
if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
return data.result;
}
async function handle(update) {
const query = update.pre_checkout_query;
if (query) {
const ok = query.invoice_payload === PAYLOAD && query.currency === "XTR"
&& query.total_amount === PRICE;
const answer = { pre_checkout_query_id: query.id, ok };
if (!ok) answer.error_message = "Esta oferta expiró. Envía /buy para recibir una factura nueva.";
await call("answerPreCheckoutQuery", answer); // en menos de 10 segundos
return;
}
const msg = update.message;
if (!msg) return;
const chatId = msg.chat.id;
if (msg.successful_payment) {
const payment = msg.successful_payment;
await appendFile("payments.jsonl", JSON.stringify({ // guarda el charge id para reembolsos
user_id: msg.from.id,
charge_id: payment.telegram_payment_charge_id,
payload: payment.invoice_payload,
amount: payment.total_amount,
}) + "\n");
await call("sendMessage", { chat_id: chatId, text: "¡Gracias! Tu Paquete Pro ya está activo." });
} else if (msg.text === "/buy") {
await call("sendInvoice", {
chat_id: chatId, title: "Paquete Pro",
description: "50 generaciones de imágenes extra para tu cuenta",
payload: PAYLOAD, provider_token: "", currency: "XTR",
prices: [{ label: "Paquete Pro", amount: PRICE }],
});
} else if (msg.text === "/paysupport") {
await call("sendMessage", {
chat_id: chatId,
text: "¿Problemas con un pago? Descríbelo en un solo mensaje y te responderemos en 24 horas.",
});
}
}
let offset = 0;
while (true) {
const updates = await call("getUpdates", {
offset, timeout: 30, allowed_updates: ["message", "pre_checkout_query"],
});
for (const update of updates) {
offset = update.update_id + 1;
await handle(update);
}
}Guarda la versión de JavaScript como bot.mjs (Node.js 18+). En producción usa una base de datos real y haz que la entrega sea idempotente por telegram_payment_charge_id. Con un webhook el handler es el mismo; revisa el webhook de un bot de Telegram para la configuración y su allowed_updates.
Reembolsar un pago con refundStarPayment
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/refundStarPayment" \
-H "Content-Type: application/json" \
-d '{"user_id": 123456789, "telegram_payment_charge_id": "CHARGE_ID_FROM_SUCCESSFUL_PAYMENT"}'
Devuelve true si sale bien, las Stars regresan al usuario y el chat recibe un mensaje de servicio con refunded_payment. Revoca lo que hayas entregado. Ten en cuenta que, si un comprador inicia un contracargo con Apple o Google, las Stars reembolsadas se descuentan del saldo del bot; Telegram aclara que esto está fuera de su control.
Saldo y transacciones: getMyStarBalance, getStarTransactions
getMyStarBalanceno recibe parámetros y devuelve el saldo actual del bot comoStarAmount.getStarTransactionsdevuelveStarTransactionsen orden cronológico; pagina conoffsetylimit(1–100, 100 por defecto). En los pagos entrantes de usuarios,StarTransaction.idcoincide con eltelegram_payment_charge_idysourcedescribe a quien pagó, lo que te permite conciliar tus registros.
Suscripciones con Telegram Stars
Pasa subscription_period a createInvoiceLink para cobrar al usuario cada 30 días:
currencydebe serXTRy, por ahora,subscription_periodsiempre debe ser2592000(30 días).- El precio de la suscripción no puede superar 10000 Stars. Un bot puede tener cualquier cantidad de suscripciones activas, incluso varias del mismo usuario.
- Cada cobro llega como
successful_payment:is_first_recurringmarca el primer pago,is_recurringlas renovaciones ysubscription_expiration_dateindica hasta cuándo está pagado el acceso. editUserStarSubscriptionconuser_id,telegram_payment_charge_ideis_canceled: truedetiene la renovación (el usuario conserva el acceso hasta el final del periodo pagado);is_canceled: falsereactiva una suscripción que canceló el bot.
Para el acceso de pago a un canal existe createChatSubscriptionInviteLink con subscription_period 2592000 y subscription_price de 1 a 10000 Stars; el bot necesita el permiso de administrador can_invite_users.
Contenido de pago, en breve
sendPaidMedia envía hasta 10 fotos o videos ocultos tras un precio: star_count de 1 a 25000 y un payload opcional de 0 a 128 bytes. En un canal, lo recaudado va al saldo del canal; en otros chats, al del bot. Si el payload no está vacío y el chat no es un canal, el bot recibe una actualización purchased_paid_media con el comprador y el payload, así que agrégala a allowed_updates si filtras actualizaciones.
Probar pagos con Stars en el entorno de pruebas
Telegram permite probar gratis los pagos con Stars en su entorno de pruebas dedicado: crea ahí una cuenta de prueba y un bot, y envía las peticiones a https://api.telegram.org/bot<token>/test/METHOD_NAME. Nuestro tester tiene un interruptor TEST para lo mismo. Las instrucciones paso a paso están en el servidor de pruebas de Telegram. Para salir a producción, cambia el bot al entorno productivo.
Checklist antes de producción y solución de problemas
- El pago se cancela tras pulsar Pagar: tu bot no respondió
pre_checkout_queryen 10 segundos. Revisa queallowed_updateslo incluya y que no se ejecute trabajo lento antes de responder. - La factura es rechazada: con Stars,
pricesdebe tener exactamente un elemento,currencydebe serXTRy no se admiten propinas. Lee ladescriptionde la respuesta de error. - Se entregó el producto sin pago: entrega con
successful_payment, nunca con el pre-checkout. - Varios compradores pagaron una misma factura: las facturas reenviadas o enviadas en grupos se pueden pagar muchas veces. Rechaza los pagos sobrantes en el pre-checkout si el pedido no puede cumplirse dos veces.
- Soporte y términos: Telegram exige que los bots respondan a
/paysupporty recomienda un comando/terms; el soporte de Telegram no puede ayudar a los usuarios con compras hechas en tu bot. - Cuenta y datos: activa la verificación en dos pasos en la cuenta dueña del bot y respalda los registros de pagos.
¿Recién empiezas con bots? Comienza por cómo crear un bot en Telegram. La referencia oficial está en la documentación de pagos con Telegram Stars y en la sección Payments de la Bot API.
Preguntas frecuentes
¿Cómo acepto pagos con Telegram Stars en un bot?
Envía una factura con sendInvoice (o createInvoiceLink) con currency XTR, un provider_token vacío y exactamente un elemento en prices. Responde la actualización pre_checkout_query con answerPreCheckoutQuery en menos de 10 segundos y entrega el producto cuando llegue un mensaje con successful_payment.
¿Necesito un provider token para Telegram Stars?
No. provider_token solo hace falta para bienes y servicios físicos. Para pagos en Telegram Stars pasa una cadena vacía o no envíes el parámetro.
¿Puedo vender productos digitales en un bot de Telegram en dólares, con tarjeta o cripto?
No. Según Telegram, los bienes y servicios digitales vendidos dentro de las apps de Telegram deben pagarse exclusivamente con Telegram Stars, por las reglas de App Store y Google Play. Otras monedas y proveedores de pago solo se permiten para bienes y servicios físicos.
¿Cómo reembolso un pago en Telegram Stars?
Llama a refundStarPayment con el user_id del comprador y el telegram_payment_charge_id del mensaje successful_payment. Guarda ese id en cada pago o no podrás reembolsarlo después.
¿Cómo funcionan las suscripciones con Telegram Stars en bots?
Crea un enlace de factura con createInvoiceLink y subscription_period = 2592000 (30 días, por ahora el único valor permitido); el precio no puede superar 10000 Stars. Las renovaciones llegan como successful_payment con is_recurring, y editUserStarSubscription cancela o reactiva la renovación.
¿Cómo pruebo los pagos con Telegram Stars sin gastar?
Usa el entorno de pruebas de Telegram: crea ahí una cuenta de prueba y un bot, y llama a la API mediante /bot<token>/test/METHOD_NAME. Telegram indica que ahí los pagos con Stars se pueden probar libremente.
Guías relacionadas
Cómo crear un bot en Telegram paso a paso: de BotFather a tu primer mensaje
Aprende a crear un bot de Telegram: /newbot en @BotFather, token, prueba con getMe y tu primer mensaje con curl y Python. Gratis y sin servidor.
Cómo desplegar un bot de Telegram: VPS, Docker y hosting serverless
Cómo desplegar un bot de Telegram: polling o webhook, servicio systemd en un VPS, Docker, Cloudflare Workers con secret_token y checklist de lanzamiento.
Telegram Bot API 10.0–10.5: ajustes del bot, widgets, rich messages, mensajes efímeros, modo invitado y más
Qué hay de nuevo en Telegram Bot API 10.0–10.5: setMySettings y BotFullInfo, widgets HTML, mensajes rich y efímeros, modo invitado, con ejemplos JSON.
Errores de la Telegram Bot API: qué significa cada uno y cómo solucionarlo
Errores de la Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict y 429 retry_after. Causas, soluciones y código de manejo.
Límites de la Telegram Bot API: rate limit, error 429, tamaño de archivos y de mensajes
Límites de la Telegram Bot API: 30 msg/s, 1 msg/s por chat, 20/min en grupos, cómo manejar 429 con retry_after y límites de tamaño de archivo y de texto.
Comandos de un bot de Telegram: setMyCommands, scopes y deep links con /start
Configura los comandos de tu bot de Telegram: /setcommands en @BotFather, setMyCommands con scopes e idiomas, parámetro de /start y /cmd@bot en grupos.
Teclados de bots de Telegram: teclado inline, botones callback y reply keyboard
Agrega botones a tu bot de Telegram: teclado inline con callback_data, answerCallbackQuery, editar el mensaje tras cada clic, reply keyboard y ForceReply.
Integración de n8n con Telegram: conecta tu bot, dispara flujos y envía mensajes
Integra n8n con Telegram: token del bot como Access Token, webhook del Telegram Trigger por HTTPS, envío de mensajes por chat id y errores comunes.
Cómo enviar mensajes con la API de Telegram: sendMessage paso a paso
Envía mensajes con la Bot API de Telegram: sendMessage con curl, Python y JavaScript, formato HTML y MarkdownV2, botones inline y errores 400, 403 y 429.
Cómo obtener el token de un bot de Telegram (y qué hacer si se filtra)
Cómo obtener el token de tu bot de Telegram con @BotFather, encontrarlo si el bot ya existe, comprobarlo con getMe y revocarlo si se filtró.
Webhook de Telegram: cómo configurar setWebhook para tu bot (Python y n8n)
Configura el webhook de tu bot de Telegram: requisitos HTTPS, setWebhook con secret_token, getWebhookInfo, handler en Python y errores típicos en n8n.
Cómo obtener el chat id de Telegram: usuarios, grupos, canales y temas
Obtén el chat id de Telegram para tu bot con getUpdates: usuarios, grupos, supergrupos (-100…), canales y temas, y qué hacer si result viene vacío.
Bot inline de Telegram: cómo activar el modo inline y responder consultas
Crea un bot inline de Telegram: activa el modo inline con @BotFather o setMySettings, procesa inline_query y responde con answerInlineQuery.
Servidor de pruebas de Telegram: cómo probar un bot en el entorno de pruebas
Usa el servidor de pruebas de Telegram: entra al entorno de pruebas, crea un bot de prueba, llama a la Bot API con /test/ y activa TEST en nuestro tester.
Widgets de Telegram para tu sitio web: iniciar sesión con Telegram, posts, comentarios y botón compartir
Integra Telegram en tu sitio: iniciar sesión con Telegram (OIDC), el Login Widget clásico con verificación del hash, posts embebidos y botón compartir.
API JavaScript de TelegramWidget: referencia, eventos, errores y límites
Referencia de la API JavaScript TelegramWidget: propiedades, request(), eventos, errores, variables CSS, widget_query, answerWidgetQuery y límites.
Ejemplos de widgets de Telegram: HTML completo y bot en Python
Ejemplos de widgets de Telegram listos para usar: tarjeta de pedido, contador con widget_query, encuesta compartida en vivo y vista previa en el navegador.
Widgets de Telegram: HTML interactivo dentro de los mensajes de tu bot
Widgets de Telegram (Bot API 10.4): qué son, cómo funcionan sendWidget, chat_data y public_data, dónde se usan hoy y en qué difieren de las Mini Apps.
Cómo probar una Mini App de Telegram: del navegador a Telegram real
Cómo probar una Mini App de Telegram: modo mock en el navegador, localhost con túnel HTTPS, entorno de prueba, DevTools y validación de initData.