مرجع الواجهة: الفواتير والاسترداد

طرق الفواتير: createInvoice و getInvoices و deleteInvoice و refundInvoice. والقواعد المشتركة (المصادقة وبنية الاستجابة والمبالغ و spend_id) في صفحة مرجع واجهة التجار؛ أما الشرح المتدرّج فهو قبول المدفوعات بالفواتير.

createInvoice

POST /pay/api/createInvoice — الصلاحية invoices، والحد 60 في الدقيقة.

الوسيط	النوع	إلزامي	المعنى
currency_type	نص	لا	crypto (الافتراضي) أو fiat
asset	نص	في وضع العملات الرقمية	العملة المطلوب تحصيلها، مثل USDT. ولا يجوز مع fiat
fiat	نص	في الوضع الورقي	العملة الورقية التي حُدّد بها السعر (أسطر is_fiat من getCurrencies)
accepted_assets	نص / مصفوفة	لا	في الوضع الورقي فقط: العملات التي يجوز للدافع الدفع بها — سلسلة مفصولة بفواصل ("USDT,GRAM") أو مصفوفة JSON. وإغفاله يعني كل العملات المدعومة
amount	نص	نعم، ما لم يُضبط open_amount	سلسلة عشرية موجبة: وحدات العملة في الوضع الرقمي، ووحدات العملة الورقية (بحد أقصى 2 منزلة عشرية) في الوضع الورقي
open_amount	منطقي	لا	امتداد، وفي الوضع الرقمي فقط: بلا مبلغ ثابت — يُدخل الدافع المبلغ عند الدفع (التبرعات والإكراميات). ولا يجتمع مع amount
description	نص	لا	حتى 1024 حرفًا، ويظهر للدافع
hidden_message	نص	لا	حتى 2048 حرفًا، ولا يُكشف للدافع إلا بعد الدفع
payload	نص	لا	حتى 4096 حرفًا من بياناتك أنت، تعود إليك في الفاتورة وفي الويب هوك
allow_comments	منطقي	لا	يسمح للدافع بإرفاق تعليق (الافتراضي true)
allow_anonymous	منطقي	لا	يسمح للدافع بإخفاء هويته (الافتراضي true)
paid_btn_name	نص	لا	زر ما بعد الدفع: viewItem أو openChannel أو openBot أو callback
paid_btn_url	نص	لا	رابط الزر http(s) — وهو إلزامي متى ضُبط paid_btn_name
swap_to	نص	لا	مبادلة المدفوعات الواردة تلقائيًا إلى هذه العملة. وتحاول المنصة تنفيذ المبادلة: فإن تعذّرت المبادلة لحظة الدفع نجحت الدفعة دون مبادلة
expires_in	عدد صحيح	لا	عدد الثواني حتى انتهاء صلاحية الفاتورة، حتى 2678400 (31 يومًا)؛ وإغفاله أو 0 يعني المدة الافتراضية. اقرأ expiration_date من النتيجة
rate_lock_seconds	عدد صحيح	لا	امتداد، وفي الوضع الورقي فقط: تثبيت أسعار التحويل لحظة الإنشاء طوال هذه المدة (انظر أدناه)

قد يُحجب الوصف ومحتوى ما بعد الدفع والزر عن الدافعين أثناء المراجعة أو إذا لم يُعتمد المحتوى. يبقى مبلغ الفاتورة قابلًا للدفع.

والنتيجة — وهي أيضًا حمولة ويب هوك invoice_paid — هي كائن الفاتورة. وأهم حقوله:

• الهوية والحالة: invoice_id و hash (المعرّف العلني داخل pay_url) و status (active / paid / expired) و pay_url — وهو رابط t.me الذي ترسله إلى الدافع (و bot_invoice_url و mini_app_invoice_url و web_app_invoice_url أسماء بديلة له).
• المبالغ: amount (القيمة الاسمية — بوحدات العملة الورقية في الفاتورة الورقية، وبالعملة الرقمية فيما عداها؛ وقيمته null ما دامت فاتورة المبلغ المفتوح غير مدفوعة) و amount_minor، وفي الفواتير الورقية المدفوعة paid_asset / paid_amount / paid_fiat_rate — أي العملة الرقمية التي حُصِّلت فعلًا والسعر المستعمل.
• الرسوم: fee_asset / fee_amount، وتُسجَّل لحظة الدفع — وهي الرقم المعتمد في دفاترك (fee و usd_rate اسمان بديلان مهجوران من Crypto Bot). راجع الرسوم والحدود.
• الدافع: paid_by_user_id (وقيمته null متى اختار الدافع إخفاء هويته) و paid_anonymously و comment.
• الاسترداد (امتداد): refunded_amount / refunded_minor (تراكميان) و refunded_at، ويُسجَّل متى استُرد المبلغ كاملًا.
• تثبيت السعر (امتداد): rate_lock_until و rate_lock_rates — وهي الأسعار المسجّلة لكل عملة، وقيمتها null إن لم يُطلب التثبيت.
• كما أُنشئت: description و hidden_message و payload و paid_btn_name / paid_btn_url و expiration_date (و expires_at اسم بديل له)، وحقول المبادلة (swap_to و is_swapped و swapped_to و swapped_rate و swapped_output…).

الأخطاء: 400 invalid_currency (خلط بين العملة الرقمية والورقية)، و 400 invalid_amount، و 400 unknown_asset، و 400 unsupported_fiat، و 400 paid_btn_url_required؛ وفي طلبات تثبيت السعر: 400 rate_lock_fiat_only و 409 ratelock_disabled و 409 rate_unavailable (لا يوجد سعر حديث لإحدى العملات المقبولة — أعد المحاولة).

كيف تُدفع الفواتير

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

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

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

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

عند انتهاء التثبيت، تبقى الفاتورة غير المنتهية قابلة للدفع بسعر لحظة الدفع. لتوحيد الموعدين، استخدم expires_in ضمن نطاق التثبيت المدعوم، وقارن expiration_date مع rate_lock_until في الاستجابة.

getInvoices

GET /pay/api/getInvoices — الصلاحية read. المرشِّحات: asset و fiat و invoice_ids (مفصولة بفواصل) و status (active / paid / expired — و expired امتداد؛ أما active فتستثني الفواتير التي تجاوزت أجلها)، إضافة إلى offset / count. تعيد {"items": [invoice, …]} بالأحدث أولًا.

deleteInvoice

POST /pay/api/deleteInvoice — الصلاحية invoices. وسيط واحد: invoice_id. يلغي فاتورة غير مدفوعة ويعيد true. الأخطاء: 404 invoice_not_found و 409 invoice_already_paid — فالفاتورة المدفوعة لا تُحذف، لأن المال قد تحرّك فعلًا.

refundInvoice

POST /pay/api/refundInvoice — الصلاحية refunds، والحد 30 في الدقيقة. وهو امتداد على Crypto Bot: يعيد كل مبلغ العملات الرقمية المدفوع فعليًا أو جزءًا منه من رصيد تطبيقك إلى الدافع، حتى لو دفع دون كشف هويته، ومن دون كشفها لك. في الفواتير المسعّرة بعملة ورقية، استخدم paid_asset وpaid_amount؛ فالاسترداد ليس تحويلًا جديدًا من العملة الورقية.

الوسيط	النوع	إلزامي	المعنى
invoice_id	عدد صحيح	نعم	الفاتورة المدفوعة
amount	نص	لا	مبلغ العملات الرقمية المطلوب استرداده بعملة الدفع الأصلية (paid_asset للفواتير المسعّرة بعملة ورقية). وإغفاله يعني كامل المتبقي غير المسترد. وتتراكم الاستردادات الجزئية حتى مبلغ العملات الرقمية المدفوع أصلًا
spend_id	نص	لا	مفتاح منع التكرار — استعمله لتعيد محاولةٌ انتهت مهلتها النتيجة نفسها بدل أن تسترد المبلغ مرتين

والنتيجة هي كائن الفاتورة بعد تحديثه ومعه refunded_amount / refunded_minor التراكميان؛ ويُسجَّل refunded_at متى استُرد المبلغ كاملًا. وتبقى الحالة paid. ولا تُعاد رسوم المنصة. يحتاج تطبيقك إلى رصيد كافٍ من عملة الدفع الأصلية، حتى لو حوّل swap_to المبلغ المستلم إلى عملة أخرى. ويطلق كل استرداد ويب هوك refund_completed الاختياري.

الأخطاء: 404 invoice_not_found و 409 invoice_not_paid و 409 already_refunded (لم يبق شيء للاسترداد) و 409 amount_too_big (أكثر من المتبقي غير المسترد) و 409 insufficient_funds و 400 invalid_amount، وزوج spend_id: 409 idempotency_conflict / 409 idempotency_in_progress.