Pembayaran Telegram Stars untuk Bot: Invoice, Pre-Checkout, Refund, dan Langganan
Untuk menerima pembayaran Telegram Stars di bot, kirim invoice dengan sendInvoice memakai mata uang XTR dan provider_token kosong, jawab update pre_checkout_query dengan answerPreCheckoutQuery dalam 10 detik, dan serahkan barang hanya setelah pesan berisi successful_payment datang. Telegram Stars adalah mata uang wajib untuk barang dan layanan digital yang dijual di aplikasi Telegram. Panduan ini membahas seluruh alurnya dengan contoh bot Python dan JavaScript yang siap jalan, lalu refund, riwayat transaksi, langganan, dan paid media.
Cara kerja pembayaran Telegram Stars di bot
Telegram Stars adalah item virtual di dalam aplikasi. Pengguna membelinya lewat in-app purchase Apple atau Google, atau lewat @PremiumBot, lalu membelanjakannya di bot kamu; form pembayaran tidak meminta data pribadi apa pun. Alurnya:
- Bot mengirim invoice:
sendInvoiceke chat, ataucreateInvoiceLinkuntuk membuat link. - Pengguna menekan Pay (membeli Stars dulu jika perlu).
- Bot menerima update berisi
pre_checkout_query. - Bot mengonfirmasi atau menolak pesanan dengan
answerPreCheckoutQuerydalam 10 detik. - Telegram mengirim pesan layanan berisi
successful_payment. - Bot menyimpan
telegram_payment_charge_iddan menyerahkan barang.
Barang digital wajib dijual dengan Stars. Telegram menyatakan bahwa bot atau Mini App harus memakai Telegram Stars untuk menjual barang dan layanan digital di aplikasi Telegram, terlepas dari situs web atau penyedia pembayaran yang kamu pakai di tempat lain; jika tidak, Telegram tidak bisa menampilkan bot kamu ke pengguna mobile. Mata uang dan penyedia pembayaran lain hanya untuk barang fisik, yang memakai alur terpisah dengan provider token.
Kirim invoice dengan sendInvoice dan XTR
Invoice Stars paling sederhana seharga 50 Stars:
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendInvoice" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"title": "Paket Pro",
"description": "50 generate gambar tambahan untuk akunmu",
"payload": "pro-pack-v1",
"provider_token": "",
"currency": "XTR",
"prices": [{"label": "Paket Pro", "amount": 50}]
}'
Method ini mengembalikan Message yang terkirim. Parameter yang penting untuk Stars:
| Parameter | Aturan untuk Telegram Stars |
|---|---|
title | Nama produk, 1–32 karakter. |
description | Deskripsi produk, 1–255 karakter. |
payload | 1–128 byte, tidak ditampilkan ke pengguna. Isi dengan ID pesanan atau produk; nilainya kembali di pre-checkout query dan di data pembayaran. |
provider_token | Opsional; isi string kosong untuk Stars. |
currency | XTR. |
prices | Array LabeledPrice yang harus berisi tepat satu item; amount adalah harga dalam Stars (bilangan bulat). |
start_parameter | Kosong: salinan yang di-forward tetap punya tombol Pay. Tidak kosong: salinan yang di-forward menampilkan tombol URL berisi deep link ke bot. |
photo_url | Gambar produk opsional, bersama photo_size, photo_width, photo_height. |
Tip (max_tip_amount) tidak didukung untuk Stars, dan need_name, need_email, need_shipping_address, is_flexible, serta field serupa diabaikan. Jika kamu menambahkan reply_markup sendiri, tombol pertama harus tombol Pay ("pay": true); substring ⭐ dan XTR di teksnya diganti dengan ikon Star. Invoice bisa dikirim ke chat pribadi, grup, dan channel. Coba tanpa kode: buka sendInvoice di Bot API Tester, isi field di atas, lalu kirim invoice ke dirimu sendiri.
createInvoiceLink untuk Mini App dan situs web
createInvoiceLink menerima title, description, payload, currency, dan prices yang sama, tetapi mengembalikan link invoice berupa string alih-alih mengirim pesan. Buka link itu dari Mini App dengan Telegram.WebApp.openInvoice(url) atau bagikan sebagai link biasa. Method ini juga dipakai untuk langganan (lihat di bawah).
Jawab pre_checkout_query dalam 10 detik
Saat pengguna menekan Pay, bot menerima PreCheckoutQuery berisi id, from, currency, total_amount, dan invoice_payload. Kamu wajib menjawab dalam 10 detik, atau transaksi dibatalkan:
ok: truejika barang tersedia dan kamu siap memproses pesanan.ok: falsepluserror_message, alasan yang mudah dipahami dan ditampilkan Telegram ke pengguna, misalnya "Penawaran ini sudah kedaluwarsa, kirim /buy untuk invoice baru".
Buat handler ini secepat mungkin: cek payload dan stok, jawab, lalu kerjakan sisanya belakangan. Menyetujui query tidak berarti uangnya sudah masuk.
Serahkan barang setelah successful_payment
Pembayaran yang berhasil datang sebagai message dengan field successful_payment berisi currency, total_amount, invoice_payload, dan telegram_payment_charge_id. Aturan Telegram jelas: selalu pastikan kamu sudah menerima successful_payment sebelum menyerahkan barang. Simpan telegram_payment_charge_id bersama user id pembeli, karena keduanya dibutuhkan untuk refund.
Contoh lengkap: bot yang berjualan dengan Telegram Stars
Bot long polling ini mengirim invoice saat menerima /buy, memvalidasi pre-checkout query, mencatat pembayaran, dan menjawab /paysupport. Perhatikan allowed_updates: jika kamu membatasi jenis update, sertakan pre_checkout_query, kalau tidak pembayaran tidak akan pernah sampai ke 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 # dalam 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"] = "Penawaran ini sudah kedaluwarsa. Kirim /buy untuk invoice baru."
call("answerPreCheckoutQuery", **answer) # dalam 10 detik
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: # simpan charge id untuk refund
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="Terima kasih! Paket Pro kamu sudah aktif.")
elif msg.get("text") == "/buy":
call("sendInvoice", chat_id=chat_id, title="Paket Pro",
description="50 generate gambar tambahan untuk akunmu",
payload=PAYLOAD, provider_token="", currency="XTR",
prices=[{"label": "Paket Pro", "amount": PRICE}])
elif msg.get("text") == "/paysupport":
call("sendMessage", chat_id=chat_id,
text="Ada masalah pembayaran? Jelaskan dalam satu pesan, kami akan membalas dalam 24 jam.")
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; // dalam 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 = "Penawaran ini sudah kedaluwarsa. Kirim /buy untuk invoice baru.";
await call("answerPreCheckoutQuery", answer); // dalam 10 detik
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({ // simpan charge id untuk refund
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: "Terima kasih! Paket Pro kamu sudah aktif." });
} else if (msg.text === "/buy") {
await call("sendInvoice", {
chat_id: chatId, title: "Paket Pro",
description: "50 generate gambar tambahan untuk akunmu",
payload: PAYLOAD, provider_token: "", currency: "XTR",
prices: [{ label: "Paket Pro", amount: PRICE }],
});
} else if (msg.text === "/paysupport") {
await call("sendMessage", {
chat_id: chatId,
text: "Ada masalah pembayaran? Jelaskan dalam satu pesan, kami akan membalas dalam 24 jam.",
});
}
}
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);
}
}Simpan versi JavaScript sebagai bot.mjs (Node.js 18+). Di produksi, pakai database sungguhan dan buat penyerahan barang idempoten per telegram_payment_charge_id. Dengan webhook handler-nya sama; cara setting dan allowed_updates-nya ada di panduan webhook telegram bot.
Refund pembayaran dengan 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"}'
Jika berhasil, method ini mengembalikan true, Stars kembali ke pengguna, dan chat menerima pesan layanan berisi refunded_payment. Cabut apa pun yang sudah kamu serahkan. Perlu dicatat: jika pembeli mengajukan chargeback ke Apple atau Google, Stars yang dikembalikan dipotong dari saldo bot; menurut Telegram, hal ini di luar kendali mereka.
Saldo dan transaksi: getMyStarBalance, getStarTransactions
getMyStarBalancetidak menerima parameter dan mengembalikan saldo bot saat ini sebagaiStarAmount.getStarTransactionsmengembalikanStarTransactionssecara kronologis; gunakanoffsetdanlimit(1–100, default 100) untuk pagination. Untuk pembayaran masuk dari pengguna,StarTransaction.idsama dengantelegram_payment_charge_id, dansourcemenjelaskan pembayarnya, sehingga kamu bisa merekonsiliasi catatanmu.
Langganan Telegram Stars
Isi subscription_period di createInvoiceLink untuk menagih pengguna setiap 30 hari:
currencyharusXTR, dansubscription_periodsaat ini harus selalu2592000(30 hari).- Harga langganan maksimal 10000 Stars. Bot boleh punya berapa pun langganan aktif, bahkan beberapa dari pengguna yang sama.
- Setiap tagihan datang sebagai
successful_payment:is_first_recurringmenandai pembayaran pertama,is_recurringmenandai perpanjangan, dansubscription_expiration_datemenunjukkan sampai kapan akses sudah dibayar. editUserStarSubscriptiondenganuser_id,telegram_payment_charge_id, danis_canceled: truemenghentikan perpanjangan (pengguna tetap punya akses sampai periode berbayar berakhir);is_canceled: falsemengaktifkan kembali langganan yang dibatalkan bot.
Untuk akses berbayar ke channel ada createChatSubscriptionInviteLink dengan subscription_period 2592000 dan subscription_price 1–10000 Stars; bot membutuhkan hak admin can_invite_users.
Sekilas tentang paid media
sendPaidMedia mengirim hingga 10 foto atau video yang tersembunyi di balik harga: star_count 1–25000 dan payload opsional 0–128 byte. Di channel, pendapatan masuk ke saldo channel; di tempat lain, ke saldo bot. Jika payload tidak kosong dan chat bukan channel, bot menerima update purchased_paid_media berisi pembeli dan payload, jadi tambahkan ke allowed_updates jika kamu memfilter update.
Tes pembayaran Stars di test environment
Telegram mengizinkan tes pembayaran Stars secara gratis di test environment khusus: buat akun dan bot uji di sana, lalu kirim request API ke https://api.telegram.org/bot<token>/test/METHOD_NAME. Tester kami punya switch TEST untuk keperluan yang sama. Langkah lengkapnya ada di panduan server tes Telegram. Untuk go-live, pindahkan bot ke environment produksi.
Checklist go-live dan troubleshooting
- Pembayaran batal setelah menekan Pay: bot tidak menjawab
pre_checkout_querydalam 10 detik. Pastikanallowed_updatesmenyertakannya dan tidak ada proses lambat sebelum jawaban. - Invoice ditolak: untuk Stars,
pricesharus berisi tepat satu item,currencyharusXTR, dan tip tidak didukung. Bacadescriptiondi respons error. - Barang terserahkan tanpa pembayaran: serahkan barang saat
successful_payment, jangan saat pre-checkout query. - Beberapa pembeli membayar satu invoice: invoice yang di-forward atau dikirim di grup bisa dibayar berkali-kali. Tolak pembayaran tambahan di tahap pre-checkout jika pesanan tidak bisa dipenuhi dua kali.
- Dukungan dan ketentuan: Telegram mewajibkan bot menjawab
/paysupportdan menyarankan perintah/terms; dukungan Telegram tidak bisa membantu pengguna terkait pembelian lewat bot kamu. - Akun dan data: aktifkan verifikasi dua langkah untuk akun pemilik bot dan backup catatan pembayaran.
Baru mulai membuat bot? Mulai dari cara membuat bot Telegram. Referensi resminya ada di dokumentasi pembayaran Telegram Stars dan bagian Payments di Bot API.
Pertanyaan umum
Bagaimana cara menerima pembayaran Telegram Stars di bot?
Kirim invoice dengan sendInvoice (atau createInvoiceLink) memakai currency XTR, provider_token kosong, dan tepat satu item di prices. Jawab update pre_checkout_query dengan answerPreCheckoutQuery dalam 10 detik, lalu serahkan barang saat pesan berisi successful_payment datang.
Apakah butuh provider token untuk Telegram Stars?
Tidak. provider_token hanya diperlukan untuk barang dan jasa fisik. Untuk pembayaran dengan Telegram Stars, isi string kosong atau jangan kirim parameter itu.
Bolehkah menjual produk digital di bot Telegram dengan dolar, kartu, atau kripto?
Tidak. Menurut Telegram, barang dan layanan digital yang dijual di aplikasi Telegram wajib dibayar hanya dengan Telegram Stars, karena aturan App Store dan Google Play. Mata uang dan penyedia pembayaran lain hanya boleh untuk barang dan jasa fisik.
Bagaimana cara refund pembayaran Telegram Stars?
Panggil refundStarPayment dengan user_id pembeli dan telegram_payment_charge_id dari pesan successful_payment. Simpan ID itu untuk setiap pembayaran, karena tanpa ID tersebut refund tidak bisa dilakukan.
Bagaimana cara kerja langganan Telegram Stars di bot?
Buat link invoice dengan createInvoiceLink dan subscription_period = 2592000 (30 hari, saat ini satu-satunya nilai yang diizinkan); harga maksimal 10000 Stars. Perpanjangan datang sebagai successful_payment dengan is_recurring, dan editUserStarSubscription membatalkan atau mengaktifkan kembali perpanjangan.
Bagaimana cara tes pembayaran Telegram Stars secara gratis?
Pakai test environment khusus dari Telegram: buat akun dan bot uji di sana, lalu panggil API lewat /bot<token>/test/METHOD_NAME. Menurut Telegram, pembayaran Stars bisa dites di sana secara bebas.
Panduan terkait
Cara Membuat Bot Telegram: dari BotFather sampai Pesan Pertama
Cara membuat bot telegram langkah demi langkah: daftar di @BotFather, simpan token, cek dengan getMe, lalu kirim pesan pertama lewat curl dan Python.
Cara Deploy Bot Telegram: Hosting di VPS, Docker, dan Serverless
Cara deploy bot Telegram: polling vs webhook, service systemd di VPS, Docker, Cloudflare Workers dengan secret_token, plus checklist sebelum bot online.
Telegram Bot API 10.0–10.5: Pengaturan Bot, Widget, Rich Message, Ephemeral Message, Guest Mode, dan Lainnya
Fitur baru Telegram Bot API 10.0–10.5: setMySettings dan BotFullInfo, widget HTML, rich message, ephemeral message, guest mode, lengkap dengan contoh JSON.
Error Telegram Bot API: Arti Setiap Error dan Cara Mengatasinya
Daftar error Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Penyebab, solusi, dan kode penanganan.
Limit Telegram Bot API: Rate Limit, Error 429, Ukuran File, dan Panjang Pesan
Limit Telegram Bot API: 30 pesan/detik, 1 pesan/detik per chat, 20/menit di grup, cara menangani 429 retry_after, batas ukuran file dan panjang pesan.
Perintah Bot Telegram: setMyCommands, Scope Perintah, dan Deep Link /start
Cara membuat perintah bot Telegram: /setcommands di @BotFather, setMyCommands dengan scope dan bahasa, parameter deep link /start, dan /cmd@bot di grup.
Keyboard Bot Telegram: Inline Keyboard, Tombol Callback, dan Reply Keyboard
Cara membuat tombol bot Telegram: inline keyboard dengan callback_data, answerCallbackQuery, edit pesan setelah tombol ditekan, reply keyboard, ForceReply.
Integrasi n8n Telegram: Hubungkan Bot, Jalankan Workflow, dan Kirim Pesan
Cara menghubungkan n8n ke Telegram: token bot sebagai Access Token, webhook Telegram Trigger via HTTPS publik, kirim pesan via chat id, dan solusi error.
Kirim Pesan Bot Telegram dengan Telegram Bot API (sendMessage)
Kirim pesan bot telegram lewat Bot API: contoh sendMessage dengan curl, Python, dan JavaScript, format HTML/MarkdownV2, tombol inline, dan solusi error.
Telegram Bot Token: Cara Mendapatkan, Mengecek, dan Mencabut Token
Cara mendapatkan token bot telegram dari @BotFather, melihat token bot lama, mengecek dengan getMe, dan me-revoke token yang bocor. Lengkap dengan contoh.
Webhook Telegram Bot: Cara Setting setWebhook, Secret Token, dan Mengatasi Error
Panduan webhook telegram bot: syarat HTTPS dan port, setWebhook dengan secret_token, cek getWebhookInfo, deleteWebhook, serta solusi error 409 dan n8n.
Chat ID Telegram Dimana? Cara Mendapatkan Chat ID User, Grup, dan Channel
Chat id telegram dimana? Cara mendapatkan chat id user, grup, supergroup, dan channel lewat getUpdates, plus solusi saat result kosong atau error 409.
Bot Inline Telegram: Cara Mengaktifkan Mode Inline dan Menjawab Inline Query
Cara membuat bot inline Telegram: aktifkan mode inline lewat @BotFather atau setMySettings, tangani update inline_query, lalu balas via answerInlineQuery.
Server Test Telegram: Cara Test Bot di Lingkungan Test Telegram
Cara memakai server test Telegram untuk bot: login ke lingkungan test, buat bot test, panggil Bot API lewat /test/, lalu aktifkan TEST di tester kami.
Widget Telegram untuk Website: Login dengan Telegram, Embed Post, Komentar, dan Tombol Share
Pasang widget telegram untuk website: login dengan Telegram (OIDC), Login Widget lama dengan cek hash, embed post, komentar channel, dan tombol share.
API JavaScript TelegramWidget: Referensi, Event, Kode Error, dan Batasan
Referensi API JavaScript TelegramWidget: properti, request(), event, kode error, variabel CSS, widget_query dan answerWidgetQuery, plus semua batasannya.
Contoh Widget Telegram: Kode HTML dan Bot Python Lengkap
Contoh widget telegram lengkap dengan kode: kartu pesanan statis, counter dengan request widget_query, polling live sebagai widget shared, preview lokal.
Widget Telegram: HTML Interaktif di Dalam Pesan Bot
Widget telegram (Bot API 10.4): apa itu, cara kerja sendWidget, chat_data dan public_data, di mana bisa dipakai saat ini, dan bedanya dengan Mini App.
Cara Tes Telegram Mini App: Dari Mock di Browser sampai Telegram Asli
Cara tes Telegram Mini App: mode mock di browser, localhost lewat tunnel HTTPS, test environment, DevTools per platform, dan validasi initData di server.