بازگشت به لیست مقالات
پرداخت و استارز

راهنمای جامع پیاده‌سازی پرداخت با استارز تلگرام (Telegram Stars)

استارز تلگرام (Telegram Stars) سیستم پرداخت رسمی و درون‌برنامه‌ای تلگرام است که به توسعه‌دهندگان و کسب‌وکارها اجازه می‌دهد محصولات دیجیتال، خدمات و اشتراک‌های ویژه را بدون خروج کاربر از محیط تلگرام و با رعایت قوانین اپ‌استور و گوگل‌پلی به فروش برسانند.

۱. ایجاد لینک فاکتور پرداخت با متد createInvoiceLink

برای ایجاد فاکتور تلگرام استارز، متد createInvoiceLink را در Bot API با واحد پول XTR فراخوانی کنید:

async function generateStarsInvoice(botToken, { title, description, payload, starsAmount }) {
  const url = `https://api.telegram.org/bot${botToken}/createInvoiceLink`;
  
  const response = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: title,
      description: description,
      payload: JSON.stringify(payload),
      currency: 'XTR',
      prices: [{ label: title, amount: starsAmount }]
    })
  });

  const data = await response.json();
  if (!data.ok) throw new Error(data.description);
  return data.result;
}

۲. باز کردن پنجره پرداخت در مینی‌اپ تلگرام

در فرانت‌اند مینی‌اپ، متد openInvoice از تلگرام SDK به کاربر اجازه می‌دهد بدون ترک صفحه فاکتور را پرداخت کند:

function buyWithStars(invoiceLink) {
  if (window.Telegram?.WebApp) {
    window.Telegram.WebApp.openInvoice(invoiceLink, (status) => {
      if (status === 'paid') {
        window.showToast('پرداخت موفقیت‌آمیز بود!', 'success');
      } else if (status === 'cancelled') {
        console.log('کاربر پرداخت را لغو کرد.');
      }
    });
  }
}

۳. اعتبارسنجی وب‌هوک‌های pre_checkout_query و successful_payment

پاسخ به pre_checkout_query باید در کمتر از ۱۰ ثانیه ارسال شود تا تلگرام مجوز کسر استارز از حساب کاربر را تایید نماید.

export default {
  async fetch(request, env) {
    const update = await request.json();

    if (update.pre_checkout_query) {
      await fetch(`https://api.telegram.org/bot${env.BOT_TOKEN}/answerPreCheckoutQuery`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          pre_checkout_query_id: update.pre_checkout_query.id,
          ok: true
        })
      });
      return new Response('OK');
    }

    if (update.message?.successful_payment) {
      const payment = update.message.successful_payment;
      await fulfillOrder(JSON.parse(payment.invoice_payload));
    }

    return new Response('OK');
  }
};