واجهة Forypay REST

كل طلب يحمل مفتاح API للمشروع كرمز bearer. تُنشأ المفاتيح في لوحة التحكم ضمن مفاتيح API، وتُعرض مرة واحدة عند الإنشاء، وتُخزَّن كبصمة فقط — فإن فقدت مفتاحًا، أبطِله وأصدر غيره.

Authorization: Bearer fp_live_9f2c…

يسجّل الدفعة التي تتوقّع استلامها ويبدأ مراقبة السلسلة. تخبرك الاستجابة بموعد إغلاق النافذة.

أضف ترويسة Idempotency-Key لتجعل إعادة المحاولة آمنة: الطلب المتكرّر بالمفتاح ذاته يُرجع الدفعة الأصلية بدل إنشاء دفعة ثانية.

curl -X POST https://your-host/api/v1/payments \
  -H "Authorization: Bearer $FP_API_KEY" \
  -H "Idempotency-Key: ORDER-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORDER-1042",
    "network": "bsc",
    "receiver": "0x2f1a…9c3e",
    "amount": "25.00",
    "expires_in": 1800
  }'

{
  "id": "pay_8Fq2mZx1LrKd",
  "order_id": "ORDER-1042",
  "network": "bsc",
  "token": "USDT",
  "amount": "25.00",
  "receiver": "0x2f1a…9c3e",
  "status": "PENDING",
  "expires_at": "2026-08-17T14:35:00.000Z"
}

يُرجع الحالة الراهنة مع كل تحويل مطابق. استخدمه للتسوية، أو كبديل إذا كانت نقطة نهاية Webhook لديك غير متاحة.

curl https://your-host/api/v1/payments/pay_8Fq2mZx1LrKd \
  -H "Authorization: Bearer $FP_API_KEY"

{
  "id": "pay_8Fq2mZx1LrKd",
  "order_id": "ORDER-1042",
  "network": "bsc",
  "token": "USDT",
  "expected_amount": "25.00",
  "detected_amount": "25.00",
  "status": "CONFIRMED",
  "transaction_hash": "0x9d4c…7b21",
  "sender": null,
  "receiver": "0x2f1a…9c3e",
  "created_at": "2026-08-17T14:05:00.000Z",
  "detected_at": "2026-08-17T14:05:12.000Z",
  "confirmed_at": "2026-08-17T14:05:21.000Z",
  "transfers": [ /* … */ ]
}

يُرجع المدفوعات الحديثة، الأحدث أولًا، مغلَّفة في مصفوفة data. أضف limit لتغيير حجم الصفحة — القيمة الافتراضية 20 والحد الأقصى 100.

curl "https://your-host/api/v1/payments?limit=50" \
  -H "Authorization: Bearer $FP_API_KEY"

فحص لمرة واحدة لبصمة تملكها مسبقًا. يقرأ السلسلة مباشرةً ولا يُنشئ سجل دفعة ولا يحدّثه — مفيد للتسوية اليدوية ولترحيل الطلبات التاريخية.

curl -X POST https://your-host/api/v1/verify \
  -H "Authorization: Bearer $FP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "bsc",
    "transaction_hash": "0x9d4c…7b21",
    "receiver": "0x2f1a…9c3e"
  }'

{
  "valid": true,
  "status": "CONFIRMED",
  "network": "bsc",
  "transaction_hash": "0x9d4c…7b21",
  "sender": "0x8f2a…1b4e",
  "receiver": "0x2f1a…9c3e",
  "amount": "25.00"
}

تبدأ الدفعة عند PENDING وتتقدّم إلى الأمام فقط. هذه هي الحالات التي ستراها في Webhooks واستجابات الواجهة ولوحة التحكم.

حدّد عنوان Webhook على المشروع، وسنرسل JSON بطلب POST مع تقدّم الدفعة. تُصطفّ الأحداث وتُعاد المحاولة بتراجع أُسّي حتى تُرجع نقطة النهاية لديك رمز 2xx، فتعامل مع المعالجات على أنها آمنة للتكرار — فقد يصل الحدث نفسه مرتين.

• payment.detected — ظهر تحويل مطابق على السلسلة وتُسوّيت الدفعة
• payment.confirmed — انتقلت الدفعة إلى حالة التسوية النهائية
• payment.expired — أُغلقت النافذة دون دفع

كل تسليم يحمل توقيع HMAC-SHA256 مشتقًّا من سرّ Webhook للمشروع، محسوبًا على ترويسة الوقت وجسم الطلب الخام موصولين بنقطة. قارنه بمقارنة ثابتة الزمن قبل الثقة بالحمولة، وارفض ما مضى عليه أكثر من خمس دقائق، ودوّر السرّ من إعدادات المشروع إن تعرّض للكشف يومًا.

POST /your/webhook
Content-Type: application/json
X-Forypay-Event: payment.confirmed
X-Forypay-Delivery: whk_3Kd9vQ2mTz
X-Forypay-Timestamp: 1755820800
X-Forypay-Signature: sha256=6f1b…a92c

{
  "event": "payment.confirmed",
  "data": {
    "payment_id": "pay_8Fq2mZx1LrKd",
    "order_id": "ORDER-1042",
    "status": "CONFIRMED",
    "transaction_hash": "0x9d4c…7b21"
  }
}

تستخدم الأخطاء رموز حالة HTTP المعتادة وجسمًا متسقًا. ويستحق request_id التسجيل — اذكره عند طلب المساعدة لنجد الطلب بعينه.

{
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Invalid amount",
    "request_id": "req_7bQ1xKp0Za"
  }
}