دليل · Telegram Stars

فواتير Telegram Stars (XTR) في البوتات: مسار الدفع للمطورين، خطوة بخطوة

بيع السلع الرقمية مقابل Stars في بوت: sendInvoice مع XTR، والرد على pre_checkout_query خلال 10 ثوانٍ، وsuccessful_payment، وتخزين معرّف الخصم وقائمة تحقق قبل الإطلاق.

تاريخ النشر:

فواتير Telegram Stars (XTR) في البوتات: مسار الدفع للمطورين، خطوة بخطوة

هل يبيع بوتك شيئًا رقميًا، مثل اشتراك أو محتوى أو طلبات ذكاء اصطناعي أو عناصر داخل اللعبة؟ إذن يكون الدفع بـ Telegram Stars فقط. يستعرض هذا المقال مسار فاتورة Telegram Stars (XTR) من وجهة نظر المطوّر، وفق وثائق Bot API الرسمية. لمعرفة سبب وجوب أن يكون الدفع بـ Stars، انظر السلع الرقمية في البوتات عبر Stars فقط.

المسار بإيجاز

الخطوةما يفعله البوتما يرسله Telegram
1sendInvoice مع currency = XTR—
2ينتظرpre_checkout_query
3answerPreCheckoutQuery (خلال 10 ثوانٍ)—
4ينتظرsuccessful_payment
5يخزّن معرّف الخصم ويسلّم السلع—

الخطوة 1: إنشاء الفاتورة

هناك طريقتان:

  • فاتورة البوت: أسلوب sendInvoice. ولأن السلع رقمية، يكون provider_token سلسلة فارغة وحقل currency هو XTR. يمكن إرسال الفاتورة إلى محادثة خاصة أو مجموعة أو قناة.
  • فاتورة مضمّنة: إذا كان بوتك يدعم الوضع المضمّن، يتيح inputInvoiceMessageContent للمستخدمين مشاركة الفاتورة مع الأصدقاء والمجموعات والقنوات. ويمكن استخدام زر الدفع فيها مرات كثيرة.

الخطوة 2: اختيار سلوك إعادة التوجيه

يتحكم المعامل start_parameter في ذلك:

  1. فاتورة متعددة المحادثات: تحتفظ النسخ المعاد توجيهها بزر الدفع، فيستطيع كثير من المستخدمين الدفع. فواتير الوضع المضمّن متعددة المحادثات دائمًا.
  2. فاتورة محادثة واحدة: قابلة للدفع فقط في المحادثة التي أُرسلت إليها؛ وتعرض النسخ المعاد توجيهها زر رابط عميق إلى البوت بدلًا من ذلك.

لاحظ أن فاتورة المحادثة الواحدة المرسلة في المحادثة الخاصة مع بوتك يمكن دفعها مرة واحدة فقط. وفي الحالتين، يقرر بوتك دائمًا ما إذا كان سيقبل دفعة جديدة.

الخطوة 3: ما قبل إتمام الدفع

يضغط المستخدم (بعد شراء Stars أولًا إن لزم) على دفع. يتلقى بوتك 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 في Bot API.

المصادر

اشترِ Stars وPremium بالدولار الأمريكي (USDT)

عبر مفتاح API: سعر Fragment، 0% (الموقع: 5%).

ابدأ الآن