قبول المدفوعات بالفواتير

الفاتورة هي وسيلتك لتحصيل المال من مستخدم في تيليجرام. تنشئها عبر الواجهة، وترسل رابطها إلى الدافع، فيُضاف المبلغ إلى رصيد تطبيقك لحظة تأكيده الدفع.

مسار الدفع

1. أنشئ الفاتورة بـ createInvoice، محدِّدًا العملة والمبلغ (أو سعرًا بعملة ورقية — انظر أدناه).
2. أرسل الرابط إلى الدافع من الاستجابة. وفتحه ينقله إلى شاشة الدفع في التطبيق.
3. يؤكّد الدافع ويدفع من رصيده — فورًا وبلا رسوم شبكة. ومن لا يكفيه رصيده يستطيع تمويل الفاتورة من محفظة خارجية، فتُسوَّى تلقائيًا حين يصل تحويله، ولا يبدو لك أي فرق.
4. يصلك الإشعار. ينطلق ويب هوك invoice_paid، ويستقر المبلغ في رصيد تطبيقك.
5. نفّذ الطلب. لا تنتظر شيئًا آخر؛ فالدفع نهائي عند هذه اللحظة.

وإن كنت تفضّل الاستعلام الدوري على الويب هوك، فإن getInvoices تعيد فواتيرك بحالتها الراهنة. والويب هوك هو المسار الأسرع، والاستعلام الدوري بديل احتياطي.

التسعير بعملة ورقية

يمكن تسعير الفاتورة بالعملات الرقمية، أو بـعملة ورقية مع قائمة بالعملات الرقمية المقبولة. عندها يدفع الدافع بأي عملة رقمية مقبولة يملكها، وتُحوَّل بسعر لحظة الدفع. وهذا هو الاختيار المعتاد لمتجر تُسعَّر منتجاته بعملة ورقية.

وإن أردت أن تعرض سعرًا ثابتًا، فإن rate_lock_seconds تثبّت أسعار التحويل لحظة الإنشاء مدةً محدودة — فيرى الدافع المبالغ المثبَّتة بالضبط، وتتحمّل أنت مخاطرة السعر طوال تلك الدقائق. التفاصيل في مرجع الفواتير.

ويمكنك أيضًا ضبط swap_to لتُبادَل المدفوعات الواردة إلى عملة واحدة فور وصولها — وهذا مفيد إن أردت إبقاء رصيدك بعملة مستقرة دون أن تدير المبادلات بنفسك.

خيارات مفيدة في الفاتورة

• description — يظهر للدافع في شاشة الدفع.
• hidden_message — لا يُكشف للدافع إلا بعد أن يدفع. وبه تسلّمه رمزًا أو مفتاحًا أو رابطًا دون قناة تسليم منفصلة.
• payload — سلسلة نصية خاصة بك تعود إليك في الويب هوك. ضع فيها معرّف طلبك.
• expires_in — مهلة زمنية لا تُقبل الفاتورة للدفع بعدها.
• paid_btn_name / paid_btn_url — الزر الذي يراه الدافع بعد الدفع، ليعود منه إلى بوتك أو قناتك أو صفحة منتجك.
• open_amount — بلا مبلغ ثابت؛ يُدخل الدافع المبلغ عند الدفع. وهو الشكل الطبيعي للتبرعات والإكراميات.

وتُلغى الفاتورة غير المدفوعة بـ deleteInvoice.

الاسترداد

تعيد refundInvoice المبلغ الاسمي لفاتورة مدفوعة — أو أي جزء منه — من رصيد تطبيقك إلى من دفعها، حتى الدافع المجهول، دون أن تنكشف لك هويته. وتتراكم الاستردادات الجزئية حتى المبلغ الاسمي، وتتابعها الفاتورة في refunded_amount. ومرّر spend_id حتى تعود المحاولة التي انتهت مهلتها بالنتيجة نفسها بدل أن تسترد المبلغ مرتين. أما رسوم المنصة فلا تُستردّ.

⚠️ تحقّق من توقيع الويب هوك قبل التنفيذ

يستطيع أي أحد أن يرسل POST إلى رابط الويب هوك لديك. فافحص الترويسة TgPayCrypto-API-Signature — وهي HMAC-SHA256 على جسم الطلب الخام، بمفتاح هو SHA-256 لرمز API لديك — قبل أن تعدّ الدفعة حقيقية، واستبعد المكرّر اعتمادًا على update_id حتى لا تشحن الطلب مرتين عند إعادة المحاولة.