Hóa đơn Telegram Stars (XTR) trong bot: quy trình thanh toán dành cho nhà phát triển, từng bước
Bán hàng hóa số bằng Stars trong bot: sendInvoice với XTR, phản hồi pre_checkout_query trong 10 giây, successful_payment, lưu ID giao dịch và danh sách kiểm tra trước khi ra mắt.
Đã đăng:

Bot của bạn có bán thứ gì đó dạng số, chẳng hạn đăng ký, nội dung, yêu cầu AI hay vật phẩm trong game? Khi đó thanh toán chỉ bằng Telegram Stars. Bài viết này đi qua quy trình hóa đơn Telegram Stars (XTR) từ góc nhìn của nhà phát triển, theo tài liệu Bot API chính thức. Về lý do phải dùng Stars, xem hàng hóa số trong bot chỉ qua Stars.
Tổng quan quy trình
| Bước | Bot làm gì | Telegram gửi gì |
|---|---|---|
| 1 | sendInvoice với currency = XTR | — |
| 2 | Chờ | pre_checkout_query |
| 3 | answerPreCheckoutQuery (trong vòng 10 giây) | — |
| 4 | Chờ | successful_payment |
| 5 | Lưu ID giao dịch, giao hàng | — |
Bước 1: tạo hóa đơn
Có hai cách:
- Hóa đơn bot: phương thức sendInvoice. Vì hàng hóa là dạng số, provider_token là chuỗi rỗng và trường currency là XTR. Hóa đơn có thể gửi vào cuộc trò chuyện riêng, nhóm hoặc kênh.
- Hóa đơn inline: nếu bot hỗ trợ chế độ inline, inputInvoiceMessageContent cho phép người dùng chia sẻ hóa đơn với bạn bè, nhóm và kênh. Nút Pay của nó có thể được dùng nhiều lần.
Bước 2: chọn hành vi chuyển tiếp
Tham số start_parameter điều khiển việc này:
- Hóa đơn đa cuộc trò chuyện: bản chuyển tiếp vẫn giữ nút Pay, nên nhiều người dùng có thể thanh toán. Hóa đơn inline luôn là đa cuộc trò chuyện.
- Hóa đơn một cuộc trò chuyện: chỉ thanh toán được trong cuộc trò chuyện đã gửi; bản chuyển tiếp hiển thị nút liên kết sâu tới bot thay thế.
Lưu ý rằng hóa đơn một cuộc trò chuyện gửi trong cuộc trò chuyện riêng với bot của bạn chỉ có thể được thanh toán một lần. Dù thế nào, bot của bạn luôn quyết định có chấp nhận khoản thanh toán mới hay không.
Bước 3: kiểm tra trước thanh toán
Người dùng (mua Stars trước nếu cần) nhấn Pay. Bot của bạn nhận pre_checkout_query kèm chi tiết đơn hàng và phải trả lời bằng answerPreCheckoutQuery trong vòng 10 giây, nếu không giao dịch sẽ bị hủy. Nếu từ chối, hãy đưa lý do dễ đọc; Telegram sẽ hiển thị cho người dùng.
Bước 4–5: thanh toán và giao hàng
Khi thanh toán thành công, tin nhắn successful_payment sẽ đến. Chỉ khi đó bạn mới nên giao hàng, vì trả lời pre_checkout_query không đảm bảo thanh toán đã hoàn tất. Hãy lưu telegram_payment_charge_id; bạn sẽ cần nó để hoàn tiền.
Trước khi ra mắt
- Bật xác minh hai bước cho tài khoản điều khiển bot.
- Cung cấp điều khoản qua /terms, và hỗ trợ qua /support và /paysupport.
- Hãy sẵn sàng cho tranh chấp và hoàn tiền bằng refundStarPayment. Xem thêm tại hoàn tiền Stars và /paysupport.
- Giữ máy chủ ổn định và sao lưu dữ liệu thanh toán.
Cách kiểm thử
Môi trường kiểm thử riêng của Telegram cho phép bạn kiểm thử thanh toán Stars miễn phí. Khi mọi thứ hoạt động, hãy chuyển sang môi trường chính thức.
Phía mua Stars
Người dùng của bạn mua Stars trong ứng dụng hoặc qua @PremiumBot, và PayStars bán chúng bằng USDT. Nếu dịch vụ của bạn cần mua Stars tự động, PayStars API và tổng quan API sẽ đề cập.
Câu hỏi thường gặp
Tôi có thể nhận tiền mã hóa hoặc đơn vị tiền tệ khác thay vì Stars không?
Không. Hàng hóa và dịch vụ số trong ứng dụng Telegram chỉ được thanh toán bằng Stars.
Làm thế nào để kiểm thử thanh toán?
Kết nối bot của bạn với môi trường kiểm thử riêng của Telegram, nơi thanh toán Stars có thể được kiểm thử miễn phí.
Làm thế nào để hoàn tiền?
Bằng phương thức refundStarPayment trong Bot API.
Nguồn
Related pages
Mua Stars và Premium bằng USD (USDT)
Qua khóa API: giá Fragment, 0% (trang web: 5%).
More news
Viết chính sách hoàn tiền cho bot Telegram Stars của bạn: mẫu và ví dụChính sách hoàn tiền cho bot Telegram Stars nên bao gồm những gì: điều kiện được hoàn, khoảng thời gian, /paysupport và refundStarPayment, cùng mẫu câu bạn có thể chỉnh sửa.Đọc →
Điều gì xảy ra với Telegram Stars của bạn nếu bạn mất quyền truy cập tài khoảnStars thuộc về tài khoản Telegram của bạn, không phải điện thoại. Tìm hiểu điều gì xảy ra với chúng khi bạn mất quyền truy cập, cách đăng nhập lại và cách bảo vệ số dư.Đọc →
Lưu sổ doanh thu Telegram Stars với tư cách người sáng tạo hoặc doanh nghiệpCách lưu sổ doanh thu Telegram Stars gọn gàng: ghi những gì, theo dõi rút tiền qua Fragment, tách cá nhân và doanh nghiệp, và nên hỏi kế toán những gì.Đọc →