مرجع MagicPay API للدفع

مرجع API

راجع الطرق والمسارات والحقول النموذجية الموثقة للبطاقات و3D Secure والاستعلام والاسترداد. ميز رد HTTP عن نتيجة الدفع.

اطلب عرضًا توضيحيًا افتح مرجع الدفع بالبطاقة

عقد المصادقة والاستجابات

تتبع نقاط النهاية دورة دفع واحدة. اربط ترويسات المصادقة وحقول استجابة كل عملية بشكل مستقل.

قبل البدء

احصل من فريق التكامل المخوّل على مفتاح API للاختبار والقيمة السرية وعنوان الاختبار عبر HTTPS. احتفظ ببيانات الاعتماد على الخادم واختر بطاقات الاختبار من صفحة الاختبار الرسمية.

ملاحظة المصدر: عنوان الاختبار موثّق عبر HTTP، وتظهر ترويسات المصادقة بشرطات عادية وسفلية. أكّد مع فريق التكامل عنوان HTTPS وصيغة الترويسات وترميز ناتج التوقيع قبل إرسال بيانات الاعتماد.

بيئة الاختبار والبطاقات مرجع المصادقة

صيغ الترويسات الواردة في المصدر

جدول Authentication

x-api-key
x-rnd-key
x-auth-version: V1
x-signature

القائمة في الصفحة نفسها

x_api_key
x_rnd_key
x_auth_version
x_signature

يصف المصدر دمج عنوان URL الكامل ومفتاح API والقيمة السرية والقيمة العشوائية لكل طلب بهذا الترتيب، ثم حساب SHA-256. لا يحدد ترميز الناتج أو تفاصيل الفواصل، لذلك لا نقدّم هنا تطبيقاً تنفيذياً للتوقيع.

المرجع الرسمي

افصل HTML المصادقة عن نتيجة الدفع

تُقرأ data.htmlContent من استجابة البدء. تستخدم استجابات الإكمال والاستعلام أسماء حقول مختلفة؛ تعرض المقاطع التالية حقولاً للتحليل وليست استجابات كاملة.

حقول استجابة الإكمال

{
  "data": {
    "paymentStatus": "SUCCESS",
    "isThreeDS": true
  }
}

المرجع الرسمي

حقول استجابة الاستعلام · مثال لعملية قيد الانتظار

{
  "data": {
    "id": 123,
    "payment_status": "WAITING"
  }
}

يستخدم مثال الإكمال data.paymentStatus، بينما يستخدم مثال الاستعلام data.payment_status. لا تعني WAITING النجاح؛ لا توحّد الاستجابتين تحت اسم حقل واحد.

المرجع الرسمي

مراجعة المصادر: 5 نوفمبر 2026

نطاق مرجع API

ست عمليات محددة

دفع بالبطاقة وخطوتا 3DS واستعلام ونطاقان للاسترداد.

حقول الطلب

وصول سريع من الحقول النموذجية إلى مراجع الطلبات والردود المفصلة.

قراءة النتيجة الصحيحة

تقييم حالة HTTP والدفع والاسترداد بشكل منفصل.

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

الدفع بالبطاقة: POST /payment/v1/card-payments

يتضمن مثال الطلب price وpaidPrice وcurrency وinstallment وcard وitems. طابق المبلغ والمبلغ المدفوع وبنود المنتجات مع بيانات طلبك؛ واستخدم Create Card Payment لتفاصيل الحقول.

3D Secure: البدء والإكمال

يتضمن مثال طلب POST /payment/v1/card-payments/3ds-init الحقل callbackUrl، وردّه data.htmlContent. يستخدم مثال POST /payment/v1/card-payments/3ds-complete الحقل paymentId. أدر عرض التحقق وعودة المستخدم والإكمال وقراءة نتيجة الدفع كخطوات منفصلة.

الاستعلام: GET /payment/v1/card-payments/{id}

يمثل id مرجع دفعة موجودة. يتضمن مثال الرد data.id وdata.payment_status وdata.refund_status. يعرض مثال HTTP 200 القيمة WAITING في payment_status؛ لذا اقرأ حالة الدفع إلى جانب حالة HTTP عند اتخاذ قرار الطلب.

الاسترداد: نطاق الدفعة والمعاملة

يتضمن مثال POST /payment/v1/refunds الحقول paymentId وconversationId وrefundDestinationType. ويستخدم مثال POST /payment/v1/refund-transactions الحقول paymentTransactionId وrefundPrice وconversationId وrefundDestinationType. اختر المعرف المطابق لنطاق الاسترداد واقرأ data.status؛ فمثال HTTP 200 للاسترداد على مستوى المعاملة يحتوي على FAIL.

ترويسات المصادقة

يسرد جدول Authentication الترويسات x-api-key وx-rnd-key وx-auth-version وx-signature، مع الإصدار V1. أكد عقد الترويسات والتوقيع الدقيق مع الفريق التقني وطبقه في إعدادات الخادم.

المراجع الرسمية لواجهة API

حلول وموارد ذات صلة

REST API

خريطة نقاط النهاية

استكشف مسار الدفع في المرجع الرسمي دون إرسال طلبات.

إنشاء دفعة بالبطاقة
POST /payment/v1/card-payments
بدء عملية 3D Secure
POST /payment/v1/card-payments/3ds-init
إتمام عملية 3D Secure
POST /payment/v1/card-payments/3ds-complete
الاستعلام عن دفعة
GET /payment/v1/card-payments/{id}
استرداد دفعة
POST /payment/v1/refunds
استرداد معاملة
POST /payment/v1/refund-transactions

الأسئلة الشائعة

كيف أميز رد HTTP عن نتيجة الدفع؟

تصف حالة HTTP رد الطلب، بينما تصف حقول الحالة في الجسم نتيجة العملية. يعرض Query Payment حالة HTTP 200 مع WAITING، ويعرض مثال الاسترداد على مستوى المعاملة HTTP 200 مع FAIL.

كيف أربط خطوات 3DS؟

استخدم data.htmlContent من رد البدء لعرض تجربة التحقق. تعامل مع العودة عبر callbackUrl وطلب الإكمال باستخدام paymentId وقراءة نتيجة الدفع كخطوات منفصلة.

أين أجد تفاصيل الحقول؟

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

مرجع API

عقد المصادقة والاستجابات

قبل البدء

صيغ الترويسات الواردة في المصدر

افصل HTML المصادقة عن نتيجة الدفع

نطاق مرجع API

ست عمليات محددة

حقول الطلب

قراءة النتيجة الصحيحة

الدفع بالبطاقة: POST /payment/v1/card-payments

3D Secure: البدء والإكمال

الاستعلام: GET /payment/v1/card-payments/{id}

الاسترداد: نطاق الدفعة والمعاملة

ترويسات المصادقة

المراجع الرسمية لواجهة API

حلول وموارد ذات صلة

الأسئلة الشائعة

ملفات تعريف الارتباط وتفضيلاتك