كيفية ربط نظام الدفع
نظام الدفع مدمج في تيليجرام. لقبول المدفوعات داخل المراسلة، يجب عليك:
- ربط نظام دفع بالبوت الخاص بك باستخدام BotFather.
- الانتقال إلى إعدادات البوت المطلوبة واختيار "المدفوعات" من القائمة.
اتبع التعليمات لربط نظام دفع متاح وانسخ الرمز المقدم.
كيفية إصدار فاتورة للعميل
لإرسال فاتورة في تيليجرام، استخدم الطريقة وحدد المعلمات المطلوبة.
tg_send_invoice(provider_token, platform_id, title, description, currency, prices, photo_url, payload, protect_content, disable_notification, need_name, need_phone_number, need_email, reply_to_message_id, reply_markup, message_thread_id, provider_data)
| معلمات الدالة | وصف المعلمة |
|---|---|
| **!** provider_token | (معلمة مطلوبة) الرمز الذي تم الحصول عليه من BotFather بعد ربط نظام الدفع |
| **!** platform_id | (معلمة مطلوبة) معرف المستلم - معرف المستخدم أو المجموعة أو القناة |
| **!** title | (معلمة مطلوبة) عنوان المنتج، 1-32 حرفًا |
| **!** description | (معلمة مطلوبة) وصف المنتج، 1-255 حرفًا |
| **!** currency | (معلمة مطلوبة) عملة الدفع (**EUR**، USD، UAH، إلخ؛ لمزيد من التفاصيل https://core.telegram.org/bots/payments#supported-currencies ) |
| prices |
مصفوفة من المصفوفات تحتوي على تفاصيل التسعير للمنتج والخدمات الإضافية (التوصيل، التغليف، إلخ). يتم عرضها في صفحة الدفع. يمكن تحديد المبلغ إما كعدد صحيح (مثل 125) أو كرقم عشري باستخدام نقطة (مثل 120.25).
على سبيل المثال: [["product", 2000], ["VAT", 20.75], ["packaging", 100]] |
| photo_url | رابط صورة المنتج |
| payload | الجزء الأول من رد الدفع، القيمة الافتراضية هي tg_payment |
| protect_content | 1 - حماية من النسخ ولقطات الشاشة، 0 - بدون حماية |
| disable_notification | 1 - إرسال مع إشعار، 0 - بدون إشعار |
| need_name | 1 - طلب الاسم الكامل للمستخدم لإكمال الطلب، 0 - بدون طلب اسم |
| need_phone_number | 1 - طلب رقم هاتف المستخدم لإكمال الطلب، 0 - بدون طلب رقم هاتف |
| need_email | 1 - طلب البريد الإلكتروني للمستخدم لإكمال الطلب، 0 - بدون طلب بريد إلكتروني |
| reply_to_message_id | معرف الرسالة للرد عليها؛ إذا كنت تريد إرسال الفاتورة كرسالة منفصلة، استخدم علامتي اقتباس مفردتين ('') |
| reply_markup | لوحة مفاتيح مع تعيين الزر الأول على النوع pay |
| message_thread_id | معرف الموضوع (متاح للمجموعات الفائقة مع تمكين وظيفة المنتدى) |
| provider_data | بيانات الفاتورة بتنسيق JSON ليتم إرسالها إلى مزود خدمة الدفع. يجب أن يوفر نظام الدفع أوصافًا تفصيلية للحقول المطلوبة. |
مهم! يجب تمرير جميع المعلمات بالترتيب المحدد في الدالة. إذا كنت بحاجة إلى تحديد معلمة معينة وتجاهل الأخرى، اترك قيمًا فارغة أو قيمًا كما هو محدد في الوثائق للمعلمات التي لا تحتاجها.
مثال:
إذا تم تمكين أي من المعلمات need_name أو need_phone_number أو need_email، سيُطلب من المستخدم تقديم تلك المعلومات قبل إتمام الدفع. عند نجاح الدفع، يتم حفظ البيانات في متغيرات العميل المقابلة.
مثال:
النتيجة: يتم طلب البيانات قبل الدفع.
رد الدفع
إذا نجح الدفع، سيتم إرسال رد بالمحتوى التالي إلى محادثة المستخدم:
tg_payment 1372995196 120.75 USD 2ff747b9-000f-5000-b000-16d7e3517aa', حيث
- course_pay - الحمولة - الحمولة من طلب إنشاء الفاتورة الأصلي؛
- 1372995196 - معرف المحادثة حيث تم إرسال الفاتورة أصلاً؛
- 120.75 - المبلغ الإجمالي للدفع؛
- USD - العملة؛
- 2ff747b9-000f-5000-b000-16d7e3517aa9 - معرف الدفع في نظام التاجر.
بالإضافة إلى ذلك، إذا تم طلب اسم المستخدم أو رقم هاتفه و/أو بريده الإلكتروني، سيتم تعيين المتغيرات المقابلة للعميل:
tg_payment_name، tg_payment_phone و tg_payment_email
سيتم إرسال رد نجاح الدفع إلى الرسائل المباشرة للمستخدم مع البوت.
يجب أن يكون لدى المستخدم محادثة موجودة مع البوت (أي يجب أن يكون قد بدأ أو اشترك في البوت) قبل إجراء الدفع. وإلا، لا يمكن للبوت إرسال الرسالة المباشرة إليه.
بمجرد استلام webhook الدفع، سيتم تأكيد الدفع تلقائيًا عبر طريقة answerPreCheckoutQuery. https://core.telegram.org/bots/api#answerprecheckoutquery
رسالة مثبتة مع زر دفع
تحتاج إلى استخدام ميزة تثبيت الرسالة بعد ربط نظام الدفع.
tg_pin_chat_message(platform_id, message_id, disable_notification)
| معلمات الدالة | الوصف |
|---|---|
| **!** platform_id | معرف محادثة تيليجرام * |
| message_id | معرف الرسالة المراد تثبيتها |
| disable_notification | تحدد هذه المعلمة ما إذا كان يجب إرسال إشعار لجميع أعضاء المحادثة حول الرسالة المثبتة حديثًا. يتم دائمًا تعطيل الإشعارات في القنوات والمحادثات الخاصة.
لتعطيل الإشعارات، قم بتعيين المعلمة disable_notification إلى 1؛ وإلا، استخدم 0. |
مثال:
الخطوة 1:
prices = [["course", 100], ["VAT", 20.75]]
result=tg_send_invoice('381764678:TEST:129736', platform_id, 'Course on courses', 'Creating courses is easy', 'USD', prices, 'https://salebot.pro/promo.png', 'course_pay','0', '0', '1', '1', '1', '', '{"inline_keyboard": [[{"text":"Pay", "pay":"True"}]]}')
الخطوة 2:
كنتيجة للخطوة الأولى، ستتلقى ردًا تحتاج منه إلى استخراج قيمة message_id باستخدام الدالة get().
res=get(result,'result')
m_id=get(res,'message_id')
بعد ذلك، قم بتثبيت الرسالة: tg_pin_chat_message(#{platform_id}, #{m_id}, 1)
مثال: مجموعة الحد الأدنى من المعلمات
prices = [["super course", 100]]
result= tg_send_invoice('381764678:TEST:129736', platform_id, 'Course on courses', 'Creating courses is super easy', 'USD', prices)
مثال: لوحة المفاتيح
prices = [["course", 100], ["VAT", 20.75]]
tg_send_invoice('381764678:TEST:129736', platform_id, 'Course on courses', 'Creating courses is easy, 'USD', prices, 'https://mavibot.ai/promo.png', 'course_pay','0', '0', '1', '1', '1', '', '{"inline_keyboard": [[{"text":"Pay", "pay":"True"}], [{"text":"Another button", "callback_data": "Another button"}]]}')
