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

آیا ربات شما چیزی دیجیتال میفروشد، مانند اشتراک، محتوا، درخواستهای هوش مصنوعی یا آیتمهای درونبازی؟ آنگاه پرداخت فقط با Telegram Stars است. این مقاله روند فاکتور Telegram Stars (XTR) را از دید توسعهدهنده و مطابق مستندات رسمی API ربات شرح میدهد. برای اینکه چرا باید Stars باشد، کالاهای دیجیتال در رباتها فقط از طریق Stars را ببینید.
نمای کلی روند
| گام | کار ربات | آنچه Telegram میفرستد |
|---|---|---|
| 1 | sendInvoice با currency = XTR | — |
| 2 | منتظر میماند | pre_checkout_query |
| 3 | answerPreCheckoutQuery (ظرف 10 ثانیه) | — |
| 4 | منتظر میماند | successful_payment |
| 5 | شناسه شارژ را ذخیره میکند و کالا را تحویل میدهد | — |
گام 1: ساخت فاکتور
دو راه وجود دارد:
- فاکتور ربات: متد sendInvoice. چون کالا دیجیتال است، provider_token یک رشته خالی است و فیلد currency برابر XTR است. فاکتور میتواند به گفتگوی خصوصی، گروه یا کانال برود.
- فاکتور درونخطی: اگر ربات شما از حالت درونخطی پشتیبانی کند، inputInvoiceMessageContent به کاربران اجازه میدهد فاکتور را با دوستان، گروهها و کانالها به اشتراک بگذارند. دکمه Pay آن را میتوان بارها استفاده کرد.
گام 2: انتخاب رفتار بازارسال
پارامتر start_parameter این را کنترل میکند:
- فاکتور چندگفتگویی: نسخههای بازارسالشده دکمه Pay را حفظ میکنند، پس کاربران زیادی میتوانند پرداخت کنند. فاکتورهای درونخطی همیشه چندگفتگویی هستند.
- فاکتور تکگفتگویی: فقط در گفتگویی که به آن فرستاده شده قابل پرداخت است؛ نسخههای بازارسالشده بهجای آن دکمه پیوند عمیق به ربات را نشان میدهند.
توجه کنید که فاکتور تکگفتگویی ارسالشده در گفتگوی خصوصی با ربات شما فقط یک بار قابل پرداخت است. در هر صورت، ربات شما همیشه تصمیم میگیرد پرداخت جدید را بپذیرد یا نه.
گام 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، ۰٪ (وبسایت: ۵٪).
More news
نوشتن سیاست بازپرداخت برای ربات Telegram Stars شما: قالب و نمونههاسیاست بازپرداخت ربات Telegram Stars باید چه چیزهایی را پوشش دهد: واجد شرایط بودن، بازه زمانی، /paysupport و refundStarPayment، بهعلاوه نمونه متنی که میتوانید متناسب کنید.بخوانید →
اگر دسترسی به حساب خود را از دست بدهید، برای Telegram Stars شما چه اتفاقی میافتدStars به حساب Telegram شما تعلق دارد، نه به تلفن شما. بدانید وقتی دسترسی را از دست میدهید چه بر سر آنها میآید، چگونه دوباره وارد شوید و چگونه از موجودی خود محافظت کنید.بخوانید →
ثبت سوابق درآمد Telegram Stars بهعنوان سازنده یا کسبوکارچگونه سوابق درآمد Telegram Stars را منظم نگه دارید: چه چیزهایی را ثبت کنید، پیگیری برداشتهای Fragment، جدا کردن امور شخصی و کسبوکار، و چه چیزی از حسابدار بپرسید.بخوانید →