التثبيت

دليل شامل من البداية إلى النهاية: تسجيل مستأجر، تثبيت إضافة DHRU، وإرسال دفعة اختبارية.

المتطلبات المسبقة

• تثبيت عامل لـ DHRU Fusion (أي إصدار حديث من PHP يدعمه DHRU نفسه).
• وصول SSH أو لوحة تحكم لوضع ملفي PHP في modules/gateways/ و modules/gateways/callback/.
• عنوان HTTPS متاح للعموم لمثيل DHRU الخاص بك (يرسل TriaPay إليه webhooks موقّعة).
• حساب مستأجر في TriaPay (سجّل من هنا).

1. أنشئ المستأجر الخاص بك

سجّل في /register باسم مستخدم وبريد إلكتروني وكلمة مرور بطول 12 حرفًا على الأقل. تحقّق من بريدك عبر الرابط الذي نرسله. سيقوم مسؤول بعدها بتفعيل المستأجر، عادةً خلال يوم عمل واحد. ستصلك رسالة ثانية عند اكتمال التفعيل.

2. أنشئ بيانات اعتماد API

سجّل الدخول. افتح صفحة Integration. يوفّر لك تبويب Webhook & API ثلاثة أشياء:

• Webhook URL — المكان الذي يرسل إليه TriaPay طلبات POST لأحداث الإيداع. اضبطه على مسار callback الخاص بـ DHRU عندك: https://yourdhru.com/modules/gateways/callback/triapay.php. إذا كان DHRU يقع تحت مسار فرعي، فضع البادئة: https://yourdomain.com/dhru/modules/gateways/callback/triapay.php.
• API key — bearer token تستخدمه إضافة DHRU لإنشاء الطلبات. اضغط Rotate للتوليد. تُعرض مرة واحدة فقط، فانسخها فورًا.
• Webhook secret — مفتاح HMAC-SHA256 تستخدمه الإضافة للتحقق من توقيعات الـ webhooks. اضغط Rotate للتوليد. يُعرض مرة واحدة فقط.

3. ثبّت إضافة DHRU

تُسلَّم الإضافة كـ ملفي PHP، كلاهما قابل للتنزيل من تبويب Webhook & API:

التنزيل	المكان
triapay.php (gateway)	<dhru-root>/modules/gateways/triapay.php
triapay-callback.php (callback، أعد تسميته إلى triapay.php)	<dhru-root>/modules/gateways/callback/triapay.php

تتمّ إعادة تسمية ملف callback أثناء التثبيت لأن DHRU يتوقّع أن يشترك ملف callback مع gateway في نفس الـ basename. نشحن التنزيل باسم مختلف فقط للإبقاء على تمييز الملفين داخل دليل /downloads/ المسطّح في TriaPay.

3a. السماح بـ callback في `.htaccess`

ملف modules/gateways/callback/.htaccess في DHRU يرفض الوصول افتراضياً ويسمح بالـ callbacks عبر تعبير FilesMatch. أضف |^triapay\.php إلى تلك القائمة كي تتمكن webhooks الخاصة بـ TriaPay من الوصول إلى الـ callback:

<FilesMatch "^wombi\.php|^gourlio\.php|...|^tripay\.php|^triapay\.php">
    Order Allow,Deny
    Allow from all
</FilesMatch>

بدون هذا التعديل، سيُرجع DHRU الخاص بك 403 Forbidden لكل عملية تسليم webhook ولن تنتقل الطلبات أبداً بعد الحالة confirmed. لا حاجة لإعادة تحميل Apache — تطبَّق تغييرات .htaccess عند الطلب التالي.

3b. تهيئة الـ gateway في DHRU

بعد الرفع، افتح لوحة DHRU → Settings → Payment Gateways → TriaPay. ألصق هذه القيم:

• API URL: https://triapay.net/api/v1
• API key: قيمة tpk_live_... التي قمت بتوليدها في الخطوة 2
• Webhook secret: القيمة التي قمت بتوليدها في الخطوة 2

احفظ.

4. اضبط طرق الاستلام

عُد إلى لوحة TriaPay → Integration:

• تبويب Crypto ← لكل chain تريد قبوله، اضبط master address الذي سيرسل العملاء إليه الأموال. TRC20 يدعم USDT فقط؛ BEP20 يقبل USDT و USDC. اختياريًا، اضبط الحدّين الأدنى/الأقصى والرسوم ضمن Advanced settings.
• تبويب Binance Pay ← اضبط Pay ID الخاص بـ Binance بالإضافة إلى API key + secret من Binance بصلاحيات Read and Pay فقط. كلٌّ من USDT و USDC مدعوم هنا. تُشفَّر بيانات الاعتماد أثناء التخزين باستخدام AES-256-GCM.

5. أرسل دفعة اختبارية

من لوحة عميل DHRU، سجّل دخولًا كمستخدم اختباري. أنشئ إيداع $1. اختر USDT TRC20 (الأسرع للتأكيد أثناء الاختبارات). أرسل المبلغ المعروض بدقّة مع لاحقة الكسور العشرية النهائية (مثل 1.0123 USDT؛ الكسور العشرية النهائية تُرمِّز كود مطابقة الطلب؛ عرضها قابل للضبط لكل طريقة من 1 إلى 3 أرقام).

تجري عملية الرصد على إيقاع ضيق: تفحص listeners الخاصة بـ TRC20 و BEP20 كل 3 ثوانٍ، و Binance Pay كل 5 ثوانٍ. إيداع الطرف-إلى-الطرف عادةً من 3 إلى 7 ثوانٍ للعملات الرقمية ومن 5 إلى 10 ثوانٍ لـ Binance Pay، بالإضافة إلى ذيل تأكيد الـ chain.

خلال ثوانٍ ستلاحظ:

1. تغيّر حالة الطلب pending → matched → credited في لوحة TriaPay عندك.
2. وضع علامة "مدفوعة" على فاتورة DHRU.
3. تحديث رصيد المستخدم.

إن توقّف شيء ما، راجع Audit log في اللوحة لمعرفة سبب الفشل.

استكشاف الأخطاء وإصلاحها

العَرَض	السبب المحتمل
طلب عالق عند confirmed ولا يصل إلى credited	فشل تسليم الـ webhook. افحص audit log للاطلاع على استجابة HTTP من DHRU. تحقّق من أن webhook URL متاح للعموم، وأن DHRU ليس خلف basic-auth، وأن webhook secret متطابق على الجانبين.
الدفع ظاهر على الـ chain لكن لا يوجد طلب مطابق	أرسل العميل مبلغًا خاطئًا أو أهمل ملاحظة Binance Pay. افتح Admin → Orphan transactions واربط يدويًا بالفاتورة الصحيحة.
الإضافة تتلقّى 429 Rate limited	الإضافة تستدعي /api/v1/orders بشدّة. الحدّ الأقصى 60 طلبًا لكل مستأجر في الدقيقة. تتضمّن الاستجابة الآن رأس Retry-After (بالثواني)، فطبّق backoff وأعد المحاولة.
401 invalid api key	إمّا أنّ API key قد جرى تدويره ولا تزال الإضافة تحتفظ بالقيمة القديمة، أو أنّ بادئة المفتاح غير مطابقة. أعد التدوير وألصق من جديد.
فشل التحقق من توقيع الـ webhook على جانب DHRU	يجب تجزئة (hash) الـ body كما استُلِم تمامًا (بايتات خام، دون إعادة ترميز). افحص X-Payment-Sig-Version: تُوقّع النسخة 2 على {timestamp}\n{idempotency}\n{body}، والنسخة 1 تُوقّع الـ body وحده. تتعامل إضافة DHRU المدمجة مع الاثنتين خلال نافذة rollover مدّتها 30 يومًا. ارفض إذا كان |now − X-Payment-Timestamp| > 300.

الخطوات التالية

• API reference — عقد REST للتكاملات المباشرة
• Webhook spec — صيغة الـ payload الكاملة والتحقق من التوقيع