كيفية ربط مزود الدفع

يحتوي تيليجرام على نظام دفع مدمج. لقبول المدفوعات داخل تيليجرام، يجب عليك:

  1. ربط مزود دفع بالبوت الخاص بك من خلال BotFather.
  2. افتح إعدادات البوت في BotFather واختر Payments.

اتبع التعليمات لربط أحد مزودي الدفع المتاحين، ثم انسخ رمز المزود الذي تم إنشاؤه.

كيفية إرسال فاتورة

لإرسال فاتورة في تيليجرام، استخدم الدالة التالية:

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 مصفوفة تصف عناصر الفاتورة. يحتوي كل عنصر على عنوان ومبلغ. يمكن أن تكون المبالغ أعدادًا صحيحة أو أعدادًا عشرية.

مثال:
[["Product", 2000], ["VAT", 20.75], ["Packaging", 100]]
photo_url رابط 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-16d7e3517aa9

حيث:

  1. tg_payment — قيمة الحمولة المحددة عند إنشاء الفاتورة.
  2. 1372995196 — معرف الدردشة حيث تم إرسال الفاتورة في الأصل.
  3. 120.75 — مبلغ الدفع.
  4. USD — عملة الدفع.
  5. 2ff747b9-000f-5000-b000-16d7e3517aa9 — معرف الدفع الذي تم إرجاعه بواسطة مزود الدفع.

إذا تم طلب معلومات العميل، سيتم أيضًا ملء متغيرات العميل التالية تلقائيًا:

  • tg_payment_name
  • tg_payment_phone
  • tg_payment_email

يتم إرسال رد الدفع إلى الدردشة الخاصة للمستخدم مع البوت.

يجب أن يكون المستخدم قد بدأ محادثة مع البوت قبل إجراء الدفع. وإلا، لا يمكن لتيليجرام تسليم رسالة رد الاتصال.

بعد استلام webhook الدفع، يقوم MaviBot تلقائيًا بتأكيد الدفع باستخدام طريقة answerPreCheckoutQuery.

https://core.telegram.org/bots/api#answerprecheckoutquery

تثبيت رسالة الفاتورة

بعد ربط مزود الدفع، يمكنك تثبيت رسالة الفاتورة.

استخدم الدالة:

tg_pin_chat_message(platform_id, message_id, disable_notification)
المعامل الوصف
platform_id معرف دردشة تيليجرام.
message_id معرف الرسالة المراد تثبيتها.
disable_notification يتحكم في ما إذا كان تيليجرام يرسل إشعارًا حول الرسالة المثبتة.

1 — بدون إشعار.
0 — إرسال إشعار.

يتم دائمًا تعطيل الإشعارات في الدردشات الخاصة والقنوات.

مثال

الخطوة 1

prices = [["Course", 100], ["VAT", 20.75]]

result = tg_send_invoice(
    '381764678:TEST:129736',
    platform_id,
    'Course',
    '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 من الرد:

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',
    'Creating courses is super easy',
    'USD',
    prices
)

مثال: فاتورة مع لوحة مفاتيح مضمنة

prices = [["Course", 100], ["VAT", 20.75]]

tg_send_invoice(
    '381764678:TEST:129736',
    platform_id,
    'Course',
    '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"}]]}'
)