Telegram Bot API

Thanh toán Telegram Stars cho bot: hóa đơn, pre-checkout, hoàn tiền và thuê bao

· 9 phút đọc

Để nhận thanh toán Telegram Stars trong bot, bạn gửi hóa đơn bằng sendInvoice với tiền tệ XTR và provider_token rỗng, trả lời update pre_checkout_query bằng answerPreCheckoutQuery trong vòng 10 giây, và chỉ giao hàng sau khi nhận được tin nhắn có successful_payment. Telegram Stars là đơn vị bắt buộc cho hàng hóa và dịch vụ số bán trong ứng dụng Telegram. Bài này đi qua toàn bộ luồng với một bot Python và JavaScript chạy được, sau đó là hoàn tiền, lịch sử giao dịch, thuê bao và paid media.

Thanh toán Telegram Stars trong bot hoạt động thế nào

Telegram Stars là vật phẩm ảo trong ứng dụng. Người dùng mua Stars qua in-app purchase của Apple, Google hoặc qua @PremiumBot rồi dùng để trả tiền trong bot của bạn; form thanh toán không hỏi bất kỳ dữ liệu cá nhân nào. Luồng xử lý:

  1. Bot gửi hóa đơn: sendInvoice vào chat, hoặc createInvoiceLink để lấy link.
  2. Người dùng bấm Pay (mua thêm Stars trước nếu thiếu).
  3. Bot nhận update có pre_checkout_query.
  4. Bot xác nhận hoặc từ chối đơn hàng bằng answerPreCheckoutQuery, trong vòng 10 giây.
  5. Telegram gửi tin nhắn dịch vụ có successful_payment.
  6. Bot lưu telegram_payment_charge_id và giao hàng.

Hàng số bắt buộc bán bằng Stars. Telegram quy định bot hoặc Mini App phải dùng Telegram Stars khi bán hàng hóa, dịch vụ số bên trong ứng dụng Telegram, bất kể bạn có website hay cổng thanh toán riêng ở nơi khác; nếu không, Telegram không thể hiển thị bot của bạn cho người dùng di động. Tiền tệ và nhà cung cấp thanh toán khác chỉ dành cho hàng vật lý, theo một luồng riêng có provider token.

Gửi hóa đơn bằng sendInvoice và XTR

Một hóa đơn Stars tối giản với giá 50 Stars:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendInvoice" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "title": "Gói Pro",
    "description": "Thêm 50 lượt tạo ảnh cho tài khoản của bạn",
    "payload": "pro-pack-v1",
    "provider_token": "",
    "currency": "XTR",
    "prices": [{"label": "Gói Pro", "amount": 50}]
  }'

Phương thức trả về Message đã gửi. Các tham số quan trọng với Stars:

Tham sốQuy tắc với Telegram Stars
titleTên sản phẩm, 1–32 ký tự.
descriptionMô tả sản phẩm, 1–255 ký tự.
payload1–128 byte, không hiển thị cho người dùng. Đặt mã đơn hàng hoặc mã sản phẩm vào đây; giá trị này quay lại trong pre-checkout query và trong thanh toán.
provider_tokenTùy chọn; với Stars thì truyền chuỗi rỗng.
currencyXTR.
pricesMảng LabeledPrice phải có đúng một mục; amount là giá tính bằng Stars (số nguyên).
start_parameterRỗng: bản chuyển tiếp vẫn giữ nút Pay. Không rỗng: bản chuyển tiếp hiện nút URL kèm deep link tới bot thay cho nút Pay.
photo_urlẢnh sản phẩm (tùy chọn), kèm photo_size, photo_width, photo_height.

Stars không hỗ trợ tiền tip (max_tip_amount), còn need_name, need_email, need_shipping_address, is_flexible và các trường tương tự sẽ bị bỏ qua. Nếu bạn tự thêm reply_markup, nút đầu tiên phải là nút Pay ("pay": true); chuỗi ⭐ và XTR trong nhãn nút sẽ được thay bằng biểu tượng Star. Hóa đơn gửi được vào chat riêng, nhóm và kênh. Thử ngay không cần code: mở sendInvoice trong Bot API Tester, điền các trường ở trên và gửi hóa đơn cho chính mình.

createInvoiceLink nhận cùng các tham số title, description, payload, currency và prices, nhưng trả về link hóa đơn dạng chuỗi thay vì gửi tin nhắn. Mở link từ Mini App bằng Telegram.WebApp.openInvoice(url) hoặc chia sẻ như link bình thường. Đây cũng là phương thức dùng cho thuê bao (xem bên dưới).

Trả lời pre_checkout_query trong 10 giây

Khi người dùng bấm Pay, bot nhận một PreCheckoutQuery gồm id, from, currency, total_amount và invoice_payload. Bạn phải trả lời trong vòng 10 giây, nếu không giao dịch sẽ bị hủy:

Handler này phải thật nhanh: kiểm tra payload và tồn kho, trả lời, mọi việc khác để sau. Xác nhận query không có nghĩa là tiền đã về.

Giao hàng sau successful_payment

Thanh toán thành công đến dưới dạng message có trường successful_payment chứa currency, total_amount, invoice_payload và telegram_payment_charge_id. Telegram nói rõ: luôn kiểm tra đã nhận successful_payment rồi mới giao hàng. Lưu telegram_payment_charge_id cùng user id của người mua, vì hoàn tiền cần cả hai.

Ví dụ hoàn chỉnh: bot bán hàng bằng Telegram Stars

Bot long polling này gửi hóa đơn khi nhận /buy, kiểm tra pre-checkout query, ghi lại thanh toán và trả lời /paysupport. Chú ý allowed_updates: nếu giới hạn loại update, phải có pre_checkout_query, nếu không thanh toán sẽ không bao giờ đến được 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  # tính bằng 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"] = "Ưu đãi đã hết hạn. Gửi /buy để nhận hóa đơn mới."
        call("answerPreCheckoutQuery", **answer)  # trong vòng 10 giây
        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:  # lưu charge id để hoàn tiền
            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="Cảm ơn bạn! Gói Pro đã được kích hoạt.")
    elif msg.get("text") == "/buy":
        call("sendInvoice", chat_id=chat_id, title="Gói Pro",
             description="Thêm 50 lượt tạo ảnh cho tài khoản của bạn",
             payload=PAYLOAD, provider_token="", currency="XTR",
             prices=[{"label": "Gói Pro", "amount": PRICE}])
    elif msg.get("text") == "/paysupport":
        call("sendMessage", chat_id=chat_id,
             text="Gặp vấn đề khi thanh toán? Mô tả trong một tin nhắn, chúng tôi sẽ trả lời trong 24 giờ.")


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; // tính bằng 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 = "Ưu đãi đã hết hạn. Gửi /buy để nhận hóa đơn mới.";
    await call("answerPreCheckoutQuery", answer); // trong vòng 10 giây
    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({ // lưu charge id để hoàn tiền
      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: "Cảm ơn bạn! Gói Pro đã được kích hoạt." });
  } else if (msg.text === "/buy") {
    await call("sendInvoice", {
      chat_id: chatId, title: "Gói Pro",
      description: "Thêm 50 lượt tạo ảnh cho tài khoản của bạn",
      payload: PAYLOAD, provider_token: "", currency: "XTR",
      prices: [{ label: "Gói Pro", amount: PRICE }],
    });
  } else if (msg.text === "/paysupport") {
    await call("sendMessage", {
      chat_id: chatId,
      text: "Gặp vấn đề khi thanh toán? Mô tả trong một tin nhắn, chúng tôi sẽ trả lời trong 24 giờ.",
    });
  }
}

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);
  }
}

Lưu bản JavaScript thành bot.mjs (Node.js 18+). Khi chạy thật, hãy dùng database và đảm bảo mỗi telegram_payment_charge_id chỉ được giao hàng một lần (idempotent). Với webhook, handler giữ nguyên; cách cài đặt và allowed_updates xem trong bài webhook Telegram bot.

Hoàn tiền bằng 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"}'

Thành công sẽ trả về true, Stars được trả lại cho người dùng và chat nhận tin nhắn dịch vụ có refunded_payment. Hãy thu hồi những gì đã giao. Lưu ý: nếu người mua yêu cầu chargeback với Apple hoặc Google, số Stars hoàn lại sẽ bị trừ vào số dư của bot; Telegram cho biết việc này nằm ngoài khả năng kiểm soát của họ.

Số dư và giao dịch: getMyStarBalance, getStarTransactions

Thuê bao Telegram Stars

Truyền subscription_period cho createInvoiceLink để thu tiền người dùng mỗi 30 ngày:

Để bán quyền truy cập kênh có createChatSubscriptionInviteLink với subscription_period 2592000 và subscription_price từ 1 đến 10000 Stars; bot cần quyền admin can_invite_users.

sendPaidMedia gửi tối đa 10 ảnh hoặc video bị ẩn sau một mức giá: star_count từ 1 đến 25000 và payload tùy chọn dài 0–128 byte. Trong kênh, doanh thu vào số dư của kênh; ở nơi khác thì vào số dư của bot. Nếu payload không rỗng và chat không phải kênh, bot nhận update purchased_paid_media kèm người mua và payload, nên hãy thêm nó vào allowed_updates nếu bạn lọc update.

Test thanh toán Stars trong môi trường test

Telegram cho phép test thanh toán Stars miễn phí trong môi trường test riêng: tạo tài khoản test và bot ở đó, rồi gửi request API tới https://api.telegram.org/bot<token>/test/METHOD_NAME. Tester của chúng tôi có công tắc TEST cho đúng mục đích này. Hướng dẫn từng bước có trong bài server test của Telegram. Khi sẵn sàng chạy thật, chuyển bot sang môi trường production.

Checklist trước khi chạy thật và xử lý sự cố

Mới làm quen với bot? Hãy bắt đầu từ bài cách tạo bot Telegram. Tài liệu chính thức nằm ở tài liệu thanh toán Telegram Stars và mục Payments của Bot API.

Câu hỏi thường gặp

Làm sao nhận thanh toán Telegram Stars trong bot?

Gửi hóa đơn bằng sendInvoice (hoặc createInvoiceLink) với currency là XTR, provider_token rỗng và đúng một mục trong prices. Trả lời update pre_checkout_query bằng answerPreCheckoutQuery trong vòng 10 giây, rồi giao hàng khi nhận được tin nhắn có successful_payment.

Có cần provider token để nhận Telegram Stars không?

Không. provider_token chỉ cần cho hàng hóa và dịch vụ vật lý. Với thanh toán bằng Telegram Stars, hãy truyền chuỗi rỗng hoặc bỏ hẳn tham số này.

Có thể bán hàng số trong bot Telegram bằng đô la, thẻ hay crypto không?

Không. Theo Telegram, hàng hóa và dịch vụ số bán bên trong ứng dụng Telegram chỉ được thanh toán bằng Telegram Stars, do quy định của App Store và Google Play. Tiền tệ và nhà cung cấp thanh toán khác chỉ dùng cho hàng hóa, dịch vụ vật lý.

Làm sao hoàn tiền một giao dịch Telegram Stars?

Gọi refundStarPayment với user_id của người mua và telegram_payment_charge_id lấy từ tin nhắn successful_payment. Hãy lưu id này cho mọi giao dịch, nếu không sau này sẽ không hoàn tiền được.

Thuê bao Telegram Stars trong bot hoạt động thế nào?

Tạo link hóa đơn bằng createInvoiceLink với subscription_period = 2592000 (30 ngày, hiện là giá trị duy nhất được phép); giá không vượt quá 10000 Stars. Mỗi lần gia hạn đến dưới dạng successful_payment có is_recurring, còn editUserStarSubscription dùng để hủy hoặc bật lại gia hạn.

Làm sao test thanh toán Telegram Stars miễn phí?

Dùng môi trường test riêng của Telegram: tạo tài khoản test và bot ở đó, rồi gọi API qua /bot<token>/test/METHOD_NAME. Telegram cho biết có thể thoải mái test thanh toán Stars trong môi trường này.

Cách tạo bot Telegram từ A đến Z: BotFather, token và tin nhắn đầu tiên

Tạo bot Telegram miễn phí với @BotFather: chọn username, lấy token, kiểm tra bằng getMe, tìm chat id và gửi tin nhắn đầu tiên bằng curl, Python.

Cách deploy bot Telegram: VPS, Docker và hosting serverless

Cách deploy bot Telegram: chọn polling hay webhook, chạy service systemd trên VPS, Docker, Cloudflare Workers với secret_token và checklist lên production.

Telegram Bot API 10.0–10.5: cài đặt bot, widget, rich message, tin nhắn ephemeral, guest mode và hơn thế

Tổng hợp thay đổi Telegram Bot API 10.0–10.5: setMySettings, BotFullInfo, widget HTML, rich message, tin nhắn ephemeral, guest mode, kèm ví dụ JSON.

Lỗi Telegram Bot API: ý nghĩa từng lỗi và cách khắc phục

Giải thích lỗi Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Nguyên nhân, cách sửa và code xử lý.

Giới hạn Telegram Bot API: rate limit, lỗi 429, dung lượng file và độ dài tin nhắn

Giới hạn Telegram Bot API: 30 tin/giây, 1 tin/giây mỗi chat, 20 tin/phút trong group, xử lý lỗi 429 retry_after, dung lượng file và độ dài tin nhắn.

Lệnh bot Telegram: setMyCommands, scope của lệnh và deep link cho /start

Cài lệnh cho bot Telegram: /setcommands trong @BotFather, setMyCommands theo scope và ngôn ngữ, tham số deep link của /start và lệnh /cmd@bot trong nhóm.

Bàn phím bot Telegram: inline keyboard, nút callback và reply keyboard

Thêm nút bấm cho bot Telegram: inline keyboard với callback_data, answerCallbackQuery, sửa tin nhắn sau khi bấm, reply keyboard và ForceReply, có code mẫu.

Tích hợp n8n với Telegram: kết nối bot, kích hoạt workflow và gửi tin nhắn

Kết nối n8n với Telegram: dùng token bot làm Access Token, Telegram Trigger cần webhook HTTPS công khai, gửi tin nhắn theo chat id và cách sửa lỗi hay gặp.

API gửi tin nhắn Telegram: hướng dẫn sendMessage với curl, Python và JavaScript

Dùng API gửi tin nhắn Telegram qua sendMessage: ví dụ curl, Python requests, JavaScript fetch, định dạng HTML, MarkdownV2, nút inline và lỗi 400, 403, 429.

Cách lấy token bot Telegram: tìm lại, kiểm tra bằng getMe và thu hồi khi bị lộ

Cách lấy token bot Telegram từ @BotFather, xem lại token của bot cũ, kiểm tra bằng getMe, sửa lỗi 401 Unauthorized và thu hồi token khi bị lộ.

Webhook Telegram bot: cài setWebhook, bảo mật bằng secret_token và dùng với n8n

Cài webhook Telegram bot từng bước: yêu cầu HTTPS và cổng, setWebhook với secret_token, kiểm tra getWebhookInfo, sửa lỗi 409 Conflict và webhook n8n.

Chat id Telegram lấy ở đâu? Cách lấy chat id cho người dùng, group, kênh và topic

Chat id Telegram lấy ở đâu: cách lấy chat id bot cho chat riêng, group, supergroup, kênh và topic bằng getUpdates, kèm cách sửa lỗi result rỗng, 409.

Bot inline Telegram: cách bật inline mode và trả lời inline query

Hướng dẫn làm bot inline Telegram: bật inline mode qua @BotFather hoặc setMySettings, xử lý update inline_query và trả kết quả bằng answerInlineQuery.

Test server Telegram: cách test bot trong môi trường thử nghiệm của Telegram

Cách dùng test server Telegram: đăng nhập môi trường test, tạo bot test, gọi Bot API qua /test/ và bật chế độ TEST trong công cụ tester của chúng tôi.

Widget Telegram cho website: Login Widget, nhúng bài đăng, bình luận và nút chia sẻ

Đăng nhập bằng Telegram trên website: Telegram Login mới (OIDC), Login Widget cũ kèm code kiểm tra hash, nhúng bài đăng, bình luận và nút chia sẻ.

TelegramWidget JavaScript API: thuộc tính, sự kiện, mã lỗi và giới hạn

Tra cứu TelegramWidget JavaScript API: thuộc tính, request(), sự kiện, mã lỗi, biến CSS, widget_query, answerWidgetQuery và mọi giới hạn của widget.

Ví dụ widget Telegram: HTML hoàn chỉnh và code bot Python

Ví dụ widget Telegram chạy được kèm code đầy đủ: thẻ đơn hàng tĩnh, bộ đếm dùng widget_query, bình chọn trực tiếp dạng widget dùng chung và stub xem thử.

Widget Telegram: HTML tương tác ngay trong tin nhắn của bot

Widget Telegram (Bot API 10.4) là gì: cách sendWidget, chat_data và public_data hoạt động, widget chạy ở đâu và khác Mini App như thế nào.

Cách test Telegram Mini App: từ mock trên trình duyệt đến Telegram thật

Hướng dẫn test Telegram Mini App: chạy mock trên trình duyệt, localhost qua tunnel HTTPS, môi trường test, DevTools từng nền tảng và xác thực initData.