نحوه فعال کردن پرداخت استارز تلگرام در ربات تلگرام
تلگرام امکان دریافت استارز را برای ربات ها فراهم کرده است. در این روش کاربر از محیط تلگرام خارج نمی شود. شما به هیچ درگاه بانکی خارجی یا واسط نیاز ندارید. تمام فرایند کسر موجودی و واریز، مستقیما روی سرورهای تلگرام پردازش می شود. این راهنما کاملا صریح و بر اساس داکیومنت رسمی API تلگرام تهیه شده است.
قوانین پایه پرداخت استارزی در تلگرام
قبل از دست بردن به کدها، باید چند قانون اصلی تلگرام را رعایت کنید:
ممنوعیت کالای فیزیکی: فروش کالای فیزیکی با استارز کاملا ممنوع است. استارز فقط برای فروش کالای دیجیتال، اشتراک کانال و خدمات درون برنامه ای کاربرد دارد.
واحد پول ثابت: پارامتر واحد پول در کدهای شما باید دقیقا عبارت XTR تنظیم شود.
حذف توکن واسط: پارامتر توکن ارائه دهنده پرداخت (Provider Token) باید یک رشته متنی کاملا خالی ارسال شود.
اعداد صحیح: استارز هیچ گونه اعشاری ندارد. ارسال عدد 50 در کد، دقیقا به معنی 50 استارز است.
مراحل کد نویسی پرداخت استارز
روند دریافت استارز شامل سه مرحله متوالی است. تفاوتی ندارد از چه زبان برنامه نویسی استفاده می کنید، منطق API در همه جا یکسان است.
مرحله اول: صدور و ارسال فاکتور پرداخت با استارز در ربات
وقتی کاربر روی دکمه خرید کلیک می کند، ربات باید یک پیش فاکتور صادر کند. برای این کار متد sendInvoice را فراخوانی کنید. این متد پارامترهای اجباری زیر را نیاز دارد:
شناسه چت کاربر (chat_id)
نام محصول (title)
توضیحات محصول (description)
یک رشته متنی دلخواه برای پیگیری در دیتابیس شما (payload)
کد ارز (currency) که باید مقدار XTR باشد.
توکن درگاه (provider_token) که باید حتما "" باشد.
آرایه قیمت ها (prices) که مبلغ نهایی را به استارز مشخص می کند.
مرحله دوم: تایید موجودی استارز کاربر
کاربر فاکتور را می بیند و روی دکمه پرداخت کلیک می کند. سرور تلگرام بررسی می کند که آیا کاربر در کیف پول خود استارز کافی دارد یا خیر. اگر موجودی کافی بود، تلگرام یک آپدیت به نام pre_checkout_query به ربات شما ارسال می کند.
ربات شما دقیقا ده ثانیه زمان دارد تا پاسخ دهد. شما باید با استفاده از متد answerPreCheckoutQuery این درخواست را تایید کنید (مقدار ok را برابر true قرار دهید). اگر در ده ثانیه جواب ندهید، فاکتور کاربر باطل می شود.
مرحله سوم: دریافت تایید نهایی تراکنش پرداخت استارزی
پس از تایید ربات شما، تلگرام استارز را از حساب کاربر کسر می کند. این مبلغ بلافاصله به موجودی ربات شما اضافه می شود. در همین لحظه، تلگرام یک آپدیت حاوی شیء successful_payment برای ربات می فرستد. دریافت این پیام به معنی قطعی شدن پرداخت است. شما در این مرحله باید دسترسی کاربر را باز کنید یا فایل دیجیتال را برای او بفرستید.
ذخیره اطلاعات برای بازگشت وجه (Refund)
درون پیام موفقیت آمیز مرحله قبل، یک شناسه بسیار مهم وجود دارد. نام این شناسه telegram_payment_charge_id است. شما موظف هستید این شناسه را همراه با مشخصات سفارش در دیتابیس خود ذخیره کنید.
اگر روزی بخواهید استارز پرداخت شده را به کاربر پس بدهید، تنها راه شما استفاده از متد refundStarPayment است. این متد بدون داشتن شناسه بالا کار نمی کند. بازگشت وجه فقط به صورت استارز انجام می شود.
نقد کردن درآمد استارز در ربات
استارز های پرداختی کاربران در بخش موجودی (Balance) ربات ذخیره می شوند. توسعه دهنده دو راه برای برداشت این موجودی دارد:
راه اول: تبدیل استارز به ارز دیجیتال تون کوین در پلتفرم فرگمنت (Fragment). این کار نیاز به انجام مراحل احراز هویت (KYC) در سایت فرگمنت دارد. توجه کنید که کاربران ایرانی برای احراز هویت در این پلتفرم با محدودیت جدی روبرو هستند.
راه دوم: صبر به مدت ۲۱ روز، برداشت استارز ها و فروش آن ها در فرگمنت
شارژ اکانت برای تست متدها
یک برنامه نویس قبل از انتشار ربات، باید کدهای پرداخت را در محیط واقعی آزمایش کند. برای طی کردن موفقیت آمیز مراحل تایید فاکتور، اکانت توسعه دهنده شما باید دارای موجودی استارز باشد. تست کردن متدها با اکانتی که موجودی صفر دارد، در مرحله دوم (pre_checkout_query) با ارور مواجه می شود.
با توجه به مسدود بودن پرداخت های بین المللی در ایران، شما می توانید برای شارژ اکانت تست خود از واسطه های داخلی استفاده کنید. برای بررسی قیمت دقیق پکیج ها و تهیه فوری موجودی، پیشنهاد می کنیم به صفحه خرید استارز تلگرام در سایت آسان استارز مراجعه کنید. پس از تهیه مقدار کمی استارز، می توانید ربات خود را به صورت عملی دیباگ کنید. همچنین می توانید لینک این صفحه را در بخش راهنمای ربات خود قرار دهید تا کاربران شما نیز بتوانند به راحتی استارز بخرند و از محصولات شما استفاده کنند.