Telegram Bot API

Telegram botlarında Stars ile ödeme: fatura, ön onay, iade ve abonelikler

· 9 dk okuma

Telegram botunda Stars ile ödeme almak için sendInvoice ile XTR para birimli ve boş provider_token içeren bir fatura gönderin, pre_checkout_query güncellemesini 10 saniye içinde answerPreCheckoutQuery ile yanıtlayın ve ürünü yalnızca successful_payment içeren mesaj geldikten sonra teslim edin. Telegram uygulamalarında satılan dijital ürün ve hizmetler için Telegram Stars zorunlu para birimidir. Bu rehberde tüm akışı çalışan bir Python ve JavaScript botuyla gösteriyor, ardından iadeleri, işlem geçmişini, abonelikleri ve ücretli medyayı anlatıyoruz.

Telegram Stars ile bot ödemesi nasıl işler?

Telegram Stars, uygulama içi sanal bir öğedir. Kullanıcılar onları Apple veya Google uygulama içi satın alımlarıyla ya da @PremiumBot üzerinden alır ve botunuzda harcar; ödeme formu hiçbir kişisel veri istemez. Akış:

  1. Bot bir fatura gönderir: sohbete sendInvoice veya bağlantı için createInvoiceLink.
  2. Kullanıcı Öde butonuna basar (gerekirse önce Stars satın alır).
  3. Bot pre_checkout_query içeren bir güncelleme alır.
  4. Bot siparişi 10 saniye içinde answerPreCheckoutQuery ile onaylar veya reddeder.
  5. Telegram successful_payment içeren bir servis mesajı gönderir.
  6. Bot telegram_payment_charge_id değerini kaydeder ve ürünü teslim eder.

Dijital ürünler Stars ile satılmalıdır. Telegram'a göre bir bot veya Mini App, Telegram uygulamaları içinde dijital ürün ve hizmet satarken başka yerde işlettiğiniz web sitesi ya da ödeme sağlayıcısından bağımsız olarak Telegram Stars kullanmak zorundadır; aksi halde Telegram botunuzu mobil kullanıcılara gösteremez. Diğer para birimleri ve ödeme sağlayıcıları yalnızca fiziksel ürünler içindir ve provider token kullanan ayrı bir akışla çalışır.

sendInvoice ve XTR ile fatura gönderme

50 Stars'lık en basit fatura:

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendInvoice" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "title": "Pro paket",
    "description": "Hesabınız için 50 ek görsel üretimi",
    "payload": "pro-pack-v1",
    "provider_token": "",
    "currency": "XTR",
    "prices": [{"label": "Pro paket", "amount": 50}]
  }'

Metot gönderilen Message nesnesini döndürür. Stars için önemli parametreler:

ParametreTelegram Stars kuralı
titleÜrün adı, 1–32 karakter.
descriptionÜrün açıklaması, 1–255 karakter.
payload1–128 bayt, kullanıcıya gösterilmez. Sipariş veya ürün kimliğinizi buraya koyun; ön onay sorgusunda ve ödemede geri gelir.
provider_tokenİsteğe bağlı; Stars için boş metin gönderin.
currencyXTR.
pricesTam olarak bir kalem içermesi gereken LabeledPrice dizisi; amount Stars cinsinden fiyattır (tam sayı).
start_parameterBoşsa iletilen kopyalarda Öde butonu kalır. Doluysa iletilen kopyalarda bunun yerine bota deep link veren bir URL butonu görünür.
photo_urlİsteğe bağlı ürün görseli; photo_size, photo_width, photo_height ile birlikte.

Bahşiş (max_tip_amount) Stars'ta desteklenmez; need_name, need_email, need_shipping_address, is_flexible ve benzeri alanlar yok sayılır. Kendi reply_markup değerinizi eklerseniz ilk buton bir Öde butonu ("pay": true) olmalıdır; metnindeki ⭐ ve XTR ifadeleri Stars simgesiyle değiştirilir. Faturalar özel sohbetlere, gruplara ve kanallara gönderilebilir. Kod yazmadan denemek için Bot API Tester'da sendInvoice metodunu açın, yukarıdaki alanları doldurun ve kendinize bir fatura gönderin.

createInvoiceLink aynı title, description, payload, currency ve prices parametrelerini alır, ancak mesaj göndermek yerine fatura bağlantısını metin olarak döndürür. Bağlantıyı bir Mini App içinden Telegram.WebApp.openInvoice(url) ile açın veya normal bir link olarak paylaşın. Abonelikler de bu metotla oluşturulur (aşağıya bakın).

pre_checkout_query'yi 10 saniye içinde yanıtlayın

Kullanıcı Öde'ye bastığında bot id, from, currency, total_amount ve invoice_payload içeren bir PreCheckoutQuery alır. 10 saniye içinde yanıt vermelisiniz, yoksa işlem iptal edilir:

Bu handler'ı hızlı tutun: payload'u ve stoğu kontrol edin, yanıtlayın, gerisini sonra yapın. Sorguyu onaylamak paranın geldiği anlamına gelmez.

Teslimatı successful_payment sonrasında yapın

Başarılı ödeme, successful_payment alanında currency, total_amount, invoice_payload ve telegram_payment_charge_id bulunan bir message olarak gelir. Telegram'ın kuralı açıktır: teslim etmeden önce mutlaka successful_payment aldığınızı kontrol edin. telegram_payment_charge_id değerini alıcının user id'siyle birlikte kaydedin; iade için ikisi de gerekir.

Tam örnek: Telegram Stars ile satış yapan bot

Bu long polling botu /buy komutuna fatura gönderir, ön onay sorgusunu doğrular, ödemeyi kaydeder ve /paysupport komutunu yanıtlar. allowed_updates'e dikkat: güncelleme türlerini kısıtlıyorsanız pre_checkout_query ekleyin, yoksa ödemeler bota hiç ulaşmaz.

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  # Telegram Stars cinsinden


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"] = "Bu teklifin süresi doldu. Yeni fatura için /buy gönderin."
        call("answerPreCheckoutQuery", **answer)  # 10 saniye içinde
        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:  # iade için charge id'yi saklayı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="Teşekkürler! Pro paketiniz etkinleştirildi.")
    elif msg.get("text") == "/buy":
        call("sendInvoice", chat_id=chat_id, title="Pro paket",
             description="Hesabınız için 50 ek görsel üretimi",
             payload=PAYLOAD, provider_token="", currency="XTR",
             prices=[{"label": "Pro paket", "amount": PRICE}])
    elif msg.get("text") == "/paysupport":
        call("sendMessage", chat_id=chat_id,
             text="Ödemeyle ilgili sorun mu var? Tek mesajda anlatın, 24 saat içinde yanıt verelim.")


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; // Telegram Stars cinsinden

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 = "Bu teklifin süresi doldu. Yeni fatura için /buy gönderin.";
    await call("answerPreCheckoutQuery", answer); // 10 saniye içinde
    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({ // iade için charge id'yi saklayı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: "Teşekkürler! Pro paketiniz etkinleştirildi." });
  } else if (msg.text === "/buy") {
    await call("sendInvoice", {
      chat_id: chatId, title: "Pro paket",
      description: "Hesabınız için 50 ek görsel üretimi",
      payload: PAYLOAD, provider_token: "", currency: "XTR",
      prices: [{ label: "Pro paket", amount: PRICE }],
    });
  } else if (msg.text === "/paysupport") {
    await call("sendMessage", {
      chat_id: chatId,
      text: "Ödemeyle ilgili sorun mu var? Tek mesajda anlatın, 24 saat içinde yanıt verelim.",
    });
  }
}

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

JavaScript sürümünü bot.mjs olarak kaydedin (Node.js 18+). Üretimde gerçek bir veritabanı kullanın ve teslimatı telegram_payment_charge_id bazında idempotent yapın. Webhook ile handler aynıdır; kurulum ve allowed_updates için Telegram bot webhook rehberine bakın.

refundStarPayment ile iade

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"}'

Başarılı olursa true döner, Stars kullanıcıya geri gider ve sohbete refunded_payment içeren bir servis mesajı düşer. Teslim ettiğiniz ürünü geri alın. Alıcı Apple veya Google üzerinden ters ibraz (chargeback) başlatırsa iade edilen Stars botun bakiyesinden düşülür; Telegram bunun kendi kontrolü dışında olduğunu belirtir.

Bakiye ve işlemler: getMyStarBalance, getStarTransactions

Telegram Stars abonelikleri

Kullanıcıdan her 30 günde bir ücret almak için createInvoiceLink'e subscription_period verin:

Kanala ücretli erişim için subscription_period 2592000 ve 1–10000 Stars arası subscription_price ile createChatSubscriptionInviteLink vardır; botun can_invite_users yönetici yetkisine ihtiyacı vardır.

sendPaidMedia, bir fiyatın arkasına gizlenmiş en fazla 10 fotoğraf veya video gönderir: star_count 1–25000 ve isteğe bağlı 0–128 baytlık payload. Kanalda gelir kanalın bakiyesine, diğer yerlerde botun bakiyesine gider. Payload doluysa ve sohbet kanal değilse bot, alıcıyı ve payload'u içeren bir purchased_paid_media güncellemesi alır; güncellemeleri filtreliyorsanız bunu allowed_updates'e ekleyin.

Stars ödemelerini test ortamında deneme

Telegram, Stars ödemelerinin ayrı test ortamında ücretsiz test edilmesine izin verir: orada bir test hesabı ve bot oluşturun, ardından API isteklerini https://api.telegram.org/bot<token>/test/METHOD_NAME adresine gönderin. Tester'ımızda aynı amaç için bir TEST anahtarı var. Adım adım talimatlar Telegram test sunucusu rehberinde. Canlıya geçmek için botu üretim ortamına taşıyın.

Canlıya geçiş kontrol listesi ve sorun giderme

Botlara yeni mi başlıyorsunuz? Telegram bot oluşturma rehberiyle başlayın. Resmî başvuru kaynakları: Telegram Stars ödemeleri dokümantasyonu ve Bot API'nin Payments bölümü.

Sık sorulan sorular

Telegram botunda Stars ile nasıl ödeme alınır?

sendInvoice (veya createInvoiceLink) ile currency = XTR, boş provider_token ve prices içinde tam olarak bir kalem olan bir fatura gönderin. pre_checkout_query güncellemesini 10 saniye içinde answerPreCheckoutQuery ile yanıtlayın, ürünü ise successful_payment içeren mesaj geldiğinde teslim edin.

Telegram Stars için provider token gerekir mi?

Hayır. provider_token yalnızca fiziksel ürün ve hizmetler için gerekir. Telegram Stars ödemelerinde boş metin gönderin veya parametreyi hiç eklemeyin.

Telegram botunda dijital ürünü dolar, kart veya kriptoyla satabilir miyim?

Hayır. Telegram'a göre Telegram uygulamaları içinde satılan dijital ürün ve hizmetler, App Store ve Google Play kuralları nedeniyle yalnızca Telegram Stars ile ödenmelidir. Diğer para birimleri ve ödeme sağlayıcıları sadece fiziksel ürün ve hizmetler için kullanılabilir.

Telegram Stars ödemesi nasıl iade edilir?

Alıcının user_id değeri ve successful_payment mesajındaki telegram_payment_charge_id ile refundStarPayment çağırın. Bu kimliği her ödeme için saklayın, aksi halde sonradan iade yapamazsınız.

Botlarda Telegram Stars aboneliği nasıl çalışır?

createInvoiceLink ile subscription_period = 2592000 (30 gün, şu an izin verilen tek değer) olan bir fatura bağlantısı oluşturun; fiyat 10000 Stars'ı aşamaz. Yenilemeler is_recurring işaretli successful_payment olarak gelir; editUserStarSubscription yenilemeyi iptal eder veya yeniden açar.

Telegram Stars ödemelerini ücretsiz nasıl test ederim?

Telegram'ın ayrı test ortamını kullanın: orada bir test hesabı ve bot oluşturup API'yi /bot<token>/test/METHOD_NAME üzerinden çağırın. Telegram'a göre Stars ödemeleri orada serbestçe test edilebilir.

Telegram bot nasıl yapılır? BotFather ile adım adım bot oluşturma

Telegram bot yapma rehberi: BotFather'da /newbot ile bot oluşturun, token'ı getMe ile test edin, chat ID'yi bulun ve Python ile ilk mesajı gönderin.

Telegram botu nasıl deploy edilir: VPS, Docker ve serverless hosting

Telegram botu sunucuya kurma: polling mi webhook mu, VPS'te systemd servisi, Docker, secret_token ile Cloudflare Workers ve yayın öncesi kontrol listesi.

Telegram Bot API 10.0–10.5: bot ayarları, widget'lar, rich mesajlar, ephemeral mesajlar, misafir modu ve dahası

Telegram Bot API 10.0–10.5'teki yenilikler: setMySettings ve BotFullInfo, HTML widget'lar, rich ve ephemeral mesajlar, misafir modu; JSON örnekleriyle.

Telegram Bot API hataları: her hata ne anlama gelir ve nasıl çözülür

Telegram Bot API hataları: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Nedenleri, çözümleri ve hata yönetimi kodu.

Telegram Bot API limitleri: mesaj gönderme hızı, 429 hatası, dosya boyutu ve mesaj uzunluğu

Telegram Bot API limitleri: saniyede 30 mesaj, sohbet başına 1 mesaj/sn, grupta dakikada 20, 429 retry_after yönetimi, dosya boyutu ve mesaj uzunluğu.

Telegram bot komutları: setMyCommands, komut kapsamları ve /start deep link

Telegram bot komutları nasıl eklenir: @BotFather /setcommands, kapsam ve dil destekli setMyCommands, /start deep link parametresi, gruplarda /komut@bot.

Telegram bot klavyeleri: inline klavye, callback butonları ve reply klavye

Telegram bot butonu ekleme: callback_data ile inline klavye, answerCallbackQuery, basıştan sonra mesajı düzenleme, reply klavye ve ForceReply örnekleri.

n8n Telegram entegrasyonu: botu bağlama, workflow tetikleme ve mesaj gönderme

n8n'i Telegram'a bağlayın: bot token'ı Access Token olarak girin, Telegram Trigger webhook'u için HTTPS kurun, chat id ile mesaj gönderin, hataları çözün.

Telegram Bot API ile mesaj gönderme (send message): curl, Python ve JavaScript

Telegram Bot API send message rehberi: curl, Python ve JavaScript ile sendMessage, HTML ve MarkdownV2 biçimlendirme, inline butonlar ve sık hatalar.

Telegram bot token nasıl alınır, nerede bulunur ve nasıl iptal edilir?

Telegram bot token nedir, BotFather'dan nasıl alınır, mevcut botun token'ı nerede bulunur? getMe ile test, 401 hatası ve sızan token'ı iptal etme.

Telegram bot webhook kurulumu: URL, secret token, getWebhookInfo ve sorun giderme

Telegram bot webhook kurulumu: setWebhook ile HTTPS URL ve secret_token ayarlayın, getWebhookInfo ile hataları görün; 409 Conflict ve n8n localhost çözümü.

Telegram chat ID nasıl bulunur: kullanıcı, grup, kanal ve konu için adım adım

Telegram chat ID nasıl bulunur? getUpdates ile kullanıcı, grup, süper grup ve kanal ID'sini öğrenin; -100 ön eki, konu ID'si ve boş result sorunu.

Telegram inline bot: inline modu açma ve inline sorguları yanıtlama

Telegram inline bot nasıl yapılır: inline modu @BotFather veya setMySettings ile açın, inline_query güncellemelerini answerInlineQuery ile yanıtlayın.

Telegram test sunucusu: Telegram botunu test ortamında nasıl test edersiniz?

Telegram test sunucusu nedir? Test ortamına giriş, test botu oluşturma, Bot API'yi /test/ ile çağırma ve Bot API Tester'da TEST modu adım adım.

Web siteniz için Telegram widget'ları: Telegram ile giriş, gönderi gömme, yorumlar ve paylaş butonu

Sitenize Telegram ile giriş ekleyin: yeni Telegram Login (OIDC), eski Login Widget ve hash kontrolü, gönderi gömme, yorumlar ve paylaş butonu.

TelegramWidget JavaScript API: özellikler, olaylar, hata kodları ve sınırlar

Telegram widget API başvurusu: TelegramWidget özellikleri, request(), olaylar, hata kodları, CSS değişkenleri, widget_query, answerWidgetQuery ve sınırlar.

Telegram widget örnekleri: eksiksiz HTML ve Python bot kodu

Çalışan Telegram widget örnekleri: statik sipariş kartı, widget_query ile sayaç, paylaşılan canlı anket ve yerel önizleme; HTML ve Python bot kodu.

Telegram widget: bot mesajının içinde çalışan etkileşimli HTML

Telegram widget nedir: Bot API 10.4'teki sendWidget, chat_data ve public_data nasıl çalışır, bugün nerede kullanılabilir, Mini App'ten farkı nedir?

Telegram Mini App nasıl test edilir: tarayıcıdaki mock'tan gerçek Telegram'a

Telegram Mini App test rehberi: tarayıcıda mock mod, HTTPS tünelle localhost, test ortamı, platformlara göre DevTools ve sunucuda initData doğrulama.