Telegram Bot API

Pembayaran Telegram Stars untuk Bot: Invoice, Pre-Checkout, Refund, dan Langganan

· 9 menit baca

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:

  1. Bot mengirim invoice: sendInvoice ke chat, atau createInvoiceLink untuk membuat link.
  2. Pengguna menekan Pay (membeli Stars dulu jika perlu).
  3. Bot menerima update berisi pre_checkout_query.
  4. Bot mengonfirmasi atau menolak pesanan dengan answerPreCheckoutQuery dalam 10 detik.
  5. Telegram mengirim pesan layanan berisi successful_payment.
  6. Bot menyimpan telegram_payment_charge_id dan 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:

ParameterAturan untuk Telegram Stars
titleNama produk, 1–32 karakter.
descriptionDeskripsi produk, 1–255 karakter.
payload1–128 byte, tidak ditampilkan ke pengguna. Isi dengan ID pesanan atau produk; nilainya kembali di pre-checkout query dan di data pembayaran.
provider_tokenOpsional; isi string kosong untuk Stars.
currencyXTR.
pricesArray LabeledPrice yang harus berisi tepat satu item; amount adalah harga dalam Stars (bilangan bulat).
start_parameterKosong: salinan yang di-forward tetap punya tombol Pay. Tidak kosong: salinan yang di-forward menampilkan tombol URL berisi deep link ke bot.
photo_urlGambar 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 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:

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

Langganan Telegram Stars

Isi subscription_period di createInvoiceLink untuk menagih pengguna setiap 30 hari:

Untuk akses berbayar ke channel ada createChatSubscriptionInviteLink dengan subscription_period 2592000 dan subscription_price 1–10000 Stars; bot membutuhkan hak admin can_invite_users.

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

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.

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.