راهنما · Telegram Stars

فاکتورهای Telegram Stars (XTR) در ربات‌ها: روند پرداخت برای توسعه‌دهندگان، گام‌به‌گام

فروش کالاهای دیجیتال در ازای Stars در یک ربات: sendInvoice با XTR، پاسخ 10 ثانیه‌ای به pre_checkout_query، successful_payment، ذخیره شناسه شارژ و چک‌لیست راه‌اندازی.

منتشرشده:

فاکتورهای Telegram Stars (XTR) در ربات‌ها: روند پرداخت برای توسعه‌دهندگان، گام‌به‌گام

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

نمای کلی روند

گامکار رباتآنچه Telegram می‌فرستد
1sendInvoice با currency = XTR—
2منتظر می‌ماندpre_checkout_query
3answerPreCheckoutQuery (ظرف 10 ثانیه)—
4منتظر می‌ماندsuccessful_payment
5شناسه شارژ را ذخیره می‌کند و کالا را تحویل می‌دهد—

گام 1: ساخت فاکتور

دو راه وجود دارد:

  • فاکتور ربات: متد sendInvoice. چون کالا دیجیتال است، provider_token یک رشته خالی است و فیلد currency برابر XTR است. فاکتور می‌تواند به گفتگوی خصوصی، گروه یا کانال برود.
  • فاکتور درون‌خطی: اگر ربات شما از حالت درون‌خطی پشتیبانی کند، inputInvoiceMessageContent به کاربران اجازه می‌دهد فاکتور را با دوستان، گروه‌ها و کانال‌ها به اشتراک بگذارند. دکمه Pay آن را می‌توان بارها استفاده کرد.

گام 2: انتخاب رفتار بازارسال

پارامتر start_parameter این را کنترل می‌کند:

  1. فاکتور چندگفتگویی: نسخه‌های بازارسال‌شده دکمه Pay را حفظ می‌کنند، پس کاربران زیادی می‌توانند پرداخت کنند. فاکتورهای درون‌خطی همیشه چندگفتگویی هستند.
  2. فاکتور تک‌گفتگویی: فقط در گفتگویی که به آن فرستاده شده قابل پرداخت است؛ نسخه‌های بازارسال‌شده به‌جای آن دکمه پیوند عمیق به ربات را نشان می‌دهند.

توجه کنید که فاکتور تک‌گفتگویی ارسال‌شده در گفتگوی خصوصی با ربات شما فقط یک بار قابل پرداخت است. در هر صورت، ربات شما همیشه تصمیم می‌گیرد پرداخت جدید را بپذیرد یا نه.

گام 3: پیش از تسویه

کاربر (در صورت نیاز ابتدا با خرید Stars) روی Pay می‌زند. ربات شما یک pre_checkout_query با جزئیات سفارش دریافت می‌کند و باید با answerPreCheckoutQuery ظرف 10 ثانیه پاسخ دهد، وگرنه تراکنش لغو می‌شود. اگر رد می‌کنید، دلیلی خوانا برای انسان بدهید؛ Telegram آن را به کاربر نشان می‌دهد.

گام‌های 4–5: تسویه و تحویل

وقتی پرداخت موفق شود، پیام successful_payment می‌رسد. فقط آن‌وقت باید تحویل دهید، چون پاسخ به pre_checkout_query تضمین نمی‌کند پرداخت انجام شده باشد. telegram_payment_charge_id را ذخیره کنید؛ برای بازپرداخت به آن نیاز دارید.

پیش از انتشار

  • برای حسابی که ربات را کنترل می‌کند تأیید دومرحله‌ای را روشن کنید.
  • شرایط را از طریق /terms و پشتیبانی را از طریق /support و /paysupport ارائه دهید.
  • برای اختلاف‌ها و بازپرداخت‌ها با refundStarPayment آماده باشید. بیشتر در بازپرداخت‌های Stars و /paysupport.
  • سرور را پایدار نگه دارید و از داده‌های پرداخت پشتیبان بگیرید.

چگونه آزمایش کنیم

محیط آزمایش اختصاصی Telegram امکان آزمایش رایگان پرداخت‌های Stars را می‌دهد. وقتی همه‌چیز کار کرد، به تولید بروید.

سمت خرید Stars

کاربران شما Stars را در اپ یا از طریق @PremiumBot می‌خرند و PayStars آن‌ها را در ازای USDT می‌فروشد. اگر سرویس خودتان باید Stars را خودکار بخرد، PayStars API و نمای کلی API آن را پوشش می‌دهند.

پرسش‌های متداول

آیا می‌توانم به‌جای Stars رمزارز یا واحد پول دیگری بپذیرم؟

خیر. کالاها و خدمات دیجیتال داخل اپ‌های Telegram فقط با Stars پرداخت می‌شوند.

چگونه پرداخت‌ها را آزمایش کنم؟

ربات خود را به محیط آزمایش اختصاصی Telegram وصل کنید؛ آنجا پرداخت‌های Stars را می‌توان رایگان آزمایش کرد.

چگونه بازپرداخت صادر کنم؟

با متد refundStarPayment در API ربات.

منابع

خرید Stars و Premium با دلار (USDT)

با کلید API: قیمت Fragment، ۰٪ (وب‌سایت: ۵٪).

شروع کنید