مرجع API

Base URL: https://triapay.net. تُصادَق طلبات server-to-server باستخدام Authorization: Bearer <api_key>. تستخدم جلسات المتصفح ملف تعريف الارتباط الذي يضعه /auth/login بالإضافة إلى رمز CSRF من /auth/csrf.

المصادقة

مستويان من المفاتيح لكل حساب:

البادئة	الاستخدام
pk_live_*	الإنتاج. لا يمكن كشفه بعد الإنشاء. درّسه للاستبدال.
pk_test_*	Sandbox. قابل للكشف من اللوحة. خاصّ بنقاط نهاية sandbox فقط.

درّس المفاتيح و webhook secrets من صفحة Integration. يتطلّب التدوير email OTP.

إنشاء طلب

POST /api/v1/orders
Authorization: Bearer pk_live_...
Content-Type: application/json

{
  "invoiceId": 12345,
  "userId": 678,
  "baseAmount": "10.00",
  "currency": "USD",
  "chain": "bep20",
  "asset": "USDT",
  "idempotencyKey": "01HT8X1V...-uuid",
  "returnUrl": "https://shop.example.com/orders/12345"
}

Field	النوع	ملاحظات
invoiceId	int	invoice id الخاص بـ DHRU عندك.
userId	int	user id الخاص بـ DHRU لنسبة الإيداع.
baseAmount	string	سلسلة عشرية. تُضاف لاحقة مبلغ صغيرة لـ crypto chains.
currency	string	عملة المصدر.
chain	enum	trc20 | bep20 | binance_pay. يقبل BEP20 و TRC20 أيضًا تحويلات Binance الداخلية (off-chain) إلى عنوان الإيداع نفسه.
asset	enum	USDT | USDC. TRC20 يدعم USDT فقط.
idempotencyKey	string	UUID. الطلبات المتكرّرة بنفس الـ payload تُعيد الطلب نفسه.
returnUrl	string	وجهة إعادة التوجيه بعد انتهاء الطلب.

الاستجابة

{
  "orderId": 4711,
  "checkoutToken": "ck_a8f3...",
  "checkoutUrl": "https://triapay.net/checkout/ck_a8f3...",
  "expectedAmount": "10.0001",
  "matchCode": 1,
  "expiresAt": "2026-05-08T05:30:00Z",
  "status": "pending"
}

أعد توجيه العميل إلى checkoutUrl. استخدم expectedAmount بصفته المبلغ الدقيق الذي يجب أن يرسله العميل.

حالة الطلب

GET /api/v1/orders/{idempotencyKey}/status
Authorization: Bearer pk_live_...

{
  "orderId": 4711,
  "status": "credited",
  "txHash": "0xabc...",
  "matchedAmount": "10.0001",
  "creditedAt": "2026-05-08T05:18:42Z"
}

تشكّل حالات الطلب آلة حالات صندوقَ-أسود:

• pending — في انتظار الدفع.
• matched — وصلت الأموال، الإيداع قيد التنفيذ.
• credited — نجاح نهائي. تمّ إقرار الـ webhook.
• expired — نهائي. لم يدفع العميل في الوقت المحدّد.
• failed — نهائي. استنفد تسليم الـ webhook المحاولات.
• overpaid — نهائي. أرسل العميل أكثر من المتوقّع. يُقيَّد الطلب ويُعلَّم للمراجعة اليدوية.

الوصولات المتأخرة (تسوية الـ chain بعد expiresAt) لا تُقيَّد تلقائيًا. استرجعها من Admin → Orphan transactions.

مساعدات sandbox

متاحة فقط مع pk_test_*. افرض الحالات النهائية دون انتظار تسوية الـ chain:

POST /api/v1/sandbox/orders/{idempotencyKey}/force-match
POST /api/v1/sandbox/orders/{idempotencyKey}/force-credit
POST /api/v1/sandbox/orders/{idempotencyKey}/force-expire
POST /api/v1/sandbox/webhook/replay

Body فارغ. تُعيد الطلب المحدَّث. تتضمّن webhooks الخاصة بـ sandbox X-Payment-Mode: sandbox؛ تقطعها إضافة DHRU المدمجة دون قيد أي فاتورة.

checkout للعميل

مصادقة بالرمز فقط. تستخدمها صفحة checkout المستضافة:

GET  /api/v1/checkout/{token}/status
GET  /api/v1/checkout/{token}/methods
POST /api/v1/checkout/{token}/select-method

Body الخاص بـ select-method: {"chain": "bep20", "asset": "USDT"}. تُعيد الطلب مع عنوان الإيداع، والمبلغ المتوقّع، و QR data URI، و match code.

الأخطاء

غلاف JSON؛ status HTTP يعكس الفئة:

{ "error": "invalid_credentials", "code": "unauthorized" }

HTTP	code	متى
400	validation_error	شكل payload غير صالح، حقول إلزامية مفقودة.
401	unauthorized	bearer أو جلسة مفقودة أو غير صالحة.
403	forbidden	IP غير موجود في allowlist، مفتاح live على نقطة sandbox-only.
404	not_found	الرمز منتهي الصلاحية، idempotency key غير معروف.
409	conflict	إعادة استخدام idempotency-key مع payload مختلف.
429	rate_limited	احترم رأس Retry-After (بالثواني).
500	internal	خطأ في الخادم. أعد المحاولة مع backoff.

تُطبَّق rate limits لكل حساب. احترم Retry-After عند كلّ 429.

Idempotency

كل طلب يغيّر الحالة يتطلّب idempotencyKey. تكرار المفتاح نفسه بـ payload نفسه يُعيد الطلب الأصلي. تكرار المفتاح نفسه بـ payload مختلف يُعيد:

{ "error": "idempotency_payload_mismatch", "code": "conflict" }

ولّد المفتاح كـ UUIDv4 لكل فاتورة واحتفظ به على جانبك حتى لا تؤدّي إعادات المحاولة بعد فشل الشبكة إلى تحصيل مزدوج.

---

تحتاج المزيد؟

أي شيء يتجاوز هذه الصفحة متاح بموجب اتفاقية شراكة. تواصل معنا عبر WhatsApp من الصفحة الرئيسية.