واجهة برمجة تطبيقات المعاملات

تغطي واجهة برمجة تطبيقات المعاملات دورة حياة الدفع الكاملة: إنشاء جلسات الدفع، والاستعلام عن حالة المعاملات، والتحقق من تأكيدات البلوك تشين.

نظرة عامة على تدفق الدفع

┌─────────────┐    ┌──────────────┐    ┌──────────────┐    ┌───────────────┐
│ Your Server │───>│ Create       │───>│ Customer     │───>│ Blockchain    │
│             │    │ Checkout     │    │ Pays on      │    │ Confirms      │
│ POST api.php│    │ Session      │    │ Payment Page │    │ Transaction   │
└─────────────┘    └──────────────┘    └──────────────┘    └───────────────┘
                         │                                        │
                         │ payment_url                             │
                         ▼                                        ▼
                   ┌──────────────┐                         ┌───────────────┐
                   │ Redirect     │                         │ Webhook POST  │
                   │ Customer     │                         │ to Your Server│
                   │ to pay.php   │                         │               │
                   └──────────────┘                         └───────────────┘

1. الخادم الخاص بكيستدعيcreate-checkout-sessionمع مبلغ الدفع والعملة.
2. تتلقىpayment_urlوتعيد توجيه العميل إليه.
3. يختار العميل عملة مشفرة، ويمسح رمز الاستجابة السريعة ضوئيًا، ويرسل الدفعة.
4. يراقب QuantaPay البلوك تشين وينتظر التأكيدات.
5. بمجرد التأكيد، يرسل QuantaPaywebhookإلى الخادم الخاص بك و/أو يعيد توجيه العميل.

create-checkout-session

إنشاء جلسة دفع جديدة. يُرجع عنوان URL للدفع لإعادة توجيه عميلك إليه.

طلب

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=create-checkout-session" \
  -d "api-key=YOUR_API_KEY" \
  -d "price=49.99" \
  -d "currency=USD"

المعلمات

تنسيق العناصر

[
  {
    "name": "Product Name",
    "qty": 2,
    "price": 24.99,
    "image": "https://example.com/product.jpg"
  }
]

• 50 عنصرًا كحد أقصى لكل جلسة.
• الاسم: 200 حرف كحد أقصى.
• الصورة: يجب أن يكون عنوان URL لـ HTTP أو HTTPS، 500 حرف كحد أقصى.

الاستجابة

{
  "success": true,
  "response": {
    "session_id": "cs_a1b2c3d4e5f6a1b2c3d4",
    "payment_url": "https://cloud.quantapay.app/pay.php?session=cs_a1b2c3d4e5f6a1b2c3d4",
    "expires_at": "2026-03-08T11:00:00+00:00"
  }
}

• session_id: معرّف جلسة فريد (التنسيق:cs_+ 24 حرفًا سداسيًا عشريًا).
• payment_url: عنوان URL لإعادة توجيه العميل لإكمال الدفع.
• expires_at: الطابع الزمني ISO 8601. تنتهي صلاحية الجلسات بعد60 دقيقة.

استجابات الخطأ

get-checkout-session

الاستعلام عن الحالة الحالية لجلسة دفع.

طلب

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=get-checkout-session" \
  -d "api-key=YOUR_API_KEY" \
  -d "session_id=cs_a1b2c3d4e5f6a1b2c3d4"

المعلمات

الاستجابة

{
  "success": true,
  "response": {
    "session_id": "cs_a1b2c3d4e5f6a1b2c3d4",
    "status": "paid",
    "price": 49.99,
    "currency": "usd",
    "order_id": "ORD-12345",
    "created_at": "2026-03-08T10:00:00+00:00",
    "expires_at": "2026-03-08T11:00:00+00:00",
    "paid_at": "2026-03-08T10:15:23+00:00"
  }
}

حالات الجلسة

get-transactions

الاستعلام عن قائمة معاملات مُرقّمة. مفيد للمطابقة وإعداد التقارير.

طلب

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=get-transactions" \
  -d "api-key=YOUR_API_KEY" \
  -d "pagination=0"

المعلمات

جميع المعلمات اختيارية:

الاستجابة

حالات المعاملات

{
  "success": true,
  "response": [
    {
      "id": "123",
      "title": "Payment #ORD-12345",
      "description": "",
      "from": "0xCustomerAddress...",
      "to": "0xYourAddress...",
      "hash": "0xTransactionHash...",
      "amount": "0.025",
      "amount_fiat": "49.99",
      "cryptocurrency": "eth",
      "currency": "usd",
      "external_reference": "",
      "creation_time": "2026-03-08 10:00:00",
      "status": "C",
      "webhook": "1",
      "vat": ""
    }
  ]
}

الرمز

transaction_id

مُعرّف المعاملة.

طلب

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=get-transaction" \
  -d "api-key=YOUR_API_KEY" \
  -d "transaction_id=123"

المعلمات

الاستجابة

قم بتشغيل فحص تأكيد البلوك تشين يدويًا لمعاملة معينة.get-transactions).

transaction

كائن المعاملة المراد فحصه (كما تم إرجاعه بواسطة

طلب

curl -X POST https://cloud.quantapay.app/api.php \
  -d "function=check-transaction" \
  -d "api-key=YOUR_API_KEY" \
  -d "transaction=TRANSACTION_JSON"

المعلمات

الاستجابة

ملاحظةC: هذه الوظيفة غير مطلوبة عادةً في التشغيل العادي. تتحقق QuantaPay تلقائيًا من التأكيدات عبر نظام cron الخاص بها. استخدم هذا فقط إذا كنت بحاجة إلى فرض فحص فوري.

Note: This function is typically not needed in normal operation. QuantaPay automatically checks confirmations via its cron system. Use this only if you need to force an immediate check.