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

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

مسار الدفع

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

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

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

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

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

ويمكنك أيضًا ضبط swap_to لتحويل المدفوعات الواردة إلى عملة واحدة عندما تكون المبادلة متاحة. إذا تعذر تنفيذها، تنجح الدفعة بالعملة الأصلية؛ راجع is_swapped وحقول swapped_*.

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

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

قد يُحجب الوصف والمحتوى المخفي وزر ما بعد الدفع عن الدافعين إلى أن يُعتمد المحتوى. لا تعتمد على ظهورها فور إنشاء الفاتورة.

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

الاسترداد

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

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

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