Telegram Bot API

Pagos con Telegram Stars en bots: facturas, pre-checkout, reembolsos y suscripciones

· 9 min de lectura

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:

  1. El bot envía una factura: sendInvoice a un chat o createInvoiceLink para obtener un enlace.
  2. El usuario pulsa Pagar (y compra Stars antes, si le faltan).
  3. El bot recibe una actualización con pre_checkout_query.
  4. El bot confirma o rechaza el pedido con answerPreCheckoutQuery en menos de 10 segundos.
  5. Telegram envía un mensaje de servicio con successful_payment.
  6. El bot guarda telegram_payment_charge_id y 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ámetroRegla para Telegram Stars
titleNombre del producto, de 1 a 32 caracteres.
descriptionDescripción del producto, de 1 a 255 caracteres.
payloadDe 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_tokenOpcional; para Stars pasa una cadena vacía.
currencyXTR.
pricesArreglo de LabeledPrice que debe tener exactamente un elemento; amount es el precio en Stars (un entero).
start_parameterVací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_urlImagen 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 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:

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

Suscripciones con Telegram Stars

Pasa subscription_period a createInvoiceLink para cobrar al usuario cada 30 días:

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.

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

¿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.

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.