عرض تجريبي مباشر

واجهة API لمدفوعات السفر

واجهة API لبوابة الدفع لحجوزات السفر: من إتمام الشراء إلى الاسترداد

تتيح واجهة API لبوابة الدفع لموقع الحجز أن يستلم أموال المسافر دون أن يلمس بيانات البطاقة أبدًا. تشرح هذه الصفحة استدعاءات عملية دفع واحدة بالبطاقة، والحالات التي تمر بها الدفعة، وما يجعل مدفوعات السفر أصعب من التجزئة، وكيف تربط PHPTRAVELS مسار الحجز لديك بالبوابة التي تختارها.

  • الجلسة و3-D Secure والتحصيل
  • كل حالات الدفعة
  • بطاقات ومحافظ وبنك وائتمان
  • لا بيانات بطاقات على خادمك

كيف تعمل الاستدعاءات

عملية دفع واحدة بالبطاقة، استدعاءً بعد استدعاء

واجهة API لبوابة الدفع هي مجموعة خدمات ويب تفتحها شركة مدفوعات للتجار. يطلب خادمك منها إنشاء دفعة بمبلغ وعملة، ويُدخل المسافر البطاقة في نموذج البوابة نفسها، وتتواصل البوابة مع شبكة البطاقات والبنك المُصدر. لا يرى خادمك رقم البطاقة أبدًا؛ بل يتلقى معرّف الدفعة وحالتها.

يشارك أربعة أطراف. يعرضها المخطط أعمدةً ويعرض كل رسالة سهمًا مرقّمًا. تختلف التسميات من بوابة إلى أخرى (payment intent أو جلسة أو طلب أو charge) لكن التسلسل واحد.

مسافر يدفع ثمن رحلة عبر الإنترنت بينما يتبادل موقع الحجز وبوابة الدفع والبنك رسائل الدفع

السهم المتقطع هو Webhook: تتصل البوابة بخادمك من تلقاء نفسها، فتُحدّث الدفعة الحجز حتى لو أغلق المسافر المتصفح. تشرح صفحة تكامل بوابات الدفع كيف يرتبط كل خطوة بالحجز في PHPTRAVELS.

  • المسافر
  • موقعك
  • البوابة
  • شبكة البطاقات / البنك

  1. 01إتمام الشراءالمسافر موقعك

    يراجع المسافر الرحلة ويضغط دفع. يُحجز الطلب لدى المورّد دون تأكيد بعد.

  2. 02إنشاء payment intent أو جلسةموقعك البوابة

    يرسل خادمك المبلغ والعملة ومرجع الحجز ومفتاح التكرار الآمن (idempotency) مع مفتاح API السري. تعيد البوابة معرّف الدفعة.

  3. 03حقول مستضافة أو إعادة توجيهالبوابة المسافر

    تقدّم البوابة نموذج البطاقة داخل صفحتك أو في صفحتها الخاصة، فتذهب بيانات البطاقة إليها مباشرة.

  4. 043-D Secureشبكة البطاقات / البنك المسافر

    إذا طلبه البنك المُصدر، يؤكد المسافر الدفع في تطبيق البنك أو برمز يُستخدم مرة واحدة.

  5. 05التفويضالبوابة شبكة البطاقات / البنك

    تطلب البوابة من المُصدر، عبر شبكة البطاقات، الموافقة على المبلغ.

  6. 06تمت الموافقة وحُجز المبلغشبكة البطاقات / البنك البوابة

    يحجز المُصدر المال على البطاقة. لم يتحرك أي مبلغ بعد.

  7. 07النتيجة إلى موقعكالبوابة موقعك

    يعود المسافر إلى موقعك بمعرّف الدفعة. يقرأ خادمك الحالة من API ويؤكد الحجز لدى المورّد.

  8. 08التحصيلموقعك البوابة

    عندما يؤكد المورّد، يحصّل خادمك المبلغ كاملًا أو أقل منه. وتستطيع بوابات كثيرة التحصيل فورًا أيضًا.

  9. 09Webhookالبوابة موقعكترسلها البوابة من تلقاء نفسها

    ترسل البوابة حدثًا موقّعًا (تم تحصيل الدفعة أو استردادها أو الاعتراض عليها) إلى نقطة النهاية لديك. يتحقق خادمك من التوقيع ويحدّث الحجز.

حالات الدفعة

دورة حياة الدفعة كآلة حالات

تُبلغ كل واجهة API لبوابة عن حالة لكل دفعة. تختلف المصطلحات لكنها تعود إلى الحالات القليلة نفسها، وعلى منطق الحجز لديك أن يتصرف تجاه كل منها.

  1. created

    أُنشئت

    الدفعة موجودة بمبلغ وعملة وتنتظر المسافر.

    failedنهائية

    فاشلة

    رُفضت، أو لم يكتمل 3-D Secure، أو تُركت. لا يُخصم شيء.

  2. authorized

    مفوّضة

    وافق المُصدر على المبلغ ويحجزه على البطاقة.

    voidedنهائية

    ملغاة

    يُلغى الحجز قبل التحصيل، فلا يُخصم من المسافر شيء.

  3. captured

    محصّلة

    أُخذ المال وسيُسوّى إلى حساب التاجر لديك.

    partially_refundedنهائية

    مستردة جزئيًا

    يُعاد جزء من المبلغ المحصّل، مثلًا بعد رسوم إلغاء.

    refundedنهائية

    مستردة

    يُعاد كامل المبلغ المحصّل إلى البطاقة.

التفويض لا يدوم إلى الأبد: إن لم يُحصَّل في الوقت المناسب ينتهي الحجز ويفرج البنك عن المال. ويمكن مواصلة استرداد دفعة مستردة جزئيًا حتى حدود المبلغ المحصّل.

لماذا السفر أصعب

لماذا تختلف مدفوعات السفر

المتجر يبيع ما في مخزونه. أما بائع السفر فيأخذ المال مقابل حجز لا يزال على المورّد تأكيده، وغالبًا قبل الرحلة بأشهر. ويجب أن تناسب واجهة الدفع هذا الواقع.

  • 01

    فوّض الآن وحصّل لاحقًا

    تُؤكَّد الفنادق عند الطلب وأسعار المجموعات والجولات بعد ساعات أو أيام من الطلب. التفويض أولًا والتحصيل عند التأكيد يعني ألا يُخصم شيء عن حجز لا يتم.

  • 02

    قد يرفض المورّد بعد الدفع

    قد ينفد سعر بين الدفع وإصدار التذكرة. مع التفويض يُفرج عن المال بإلغاء الحجز؛ وبعد التحصيل يصبح استردادًا.

  • 03

    استرداد جزئي بعد رسوم الإلغاء

    إلغاء إقامة أو تذكرة يُبقي عادةً رسومًا. يرسل استدعاء الاسترداد مبلغًا أقل مقابل الدفعة الأصلية، بقدر ما تقتضي الشروط.

  • 04

    عملات متعددة

    يدفع المسافرون بعملتهم بينما يفوتر المورّدون بعملتهم. يجب أن تدعم البوابة عملة العرض، وأن تحتفظ سجلاتك بالمبلغين.

  • 05

    فحوص احتيال للمبالغ الكبيرة

    تذاكر ليوم غد، لشخص آخر، مدفوعة ببطاقة جديدة، نمط احتيال معروف. يحمي 3-D Secure وتقييم المخاطر في البوابة وطابور مراجعة يدوية الطلبات عالية القيمة.

  • 06

    مطالبات استرداد بعد أشهر

    تصل الاعتراضات غالبًا بعد السفر. احتفظ بنتيجة المصادقة ووثائق الحجز وأحداث البوابة معًا لتردّ بالأدلة.

طرق الدفع

أي طرق دفع تغطيها واجهة API لبوابة الدفع

البطاقات خيار واحد فقط. يدفع المسافرون والوكلاء بطرق مختلفة، ولكل طريقة أسلوب استرداد مختلف.

الطريقةما هيمتى يصل المالالاسترداد
البطاقاتبطاقات الخصم والائتمان عبر البوابة، مع 3-D Secure حيث يطلبه المُصدر.تُفوَّض عند إتمام الشراء؛ وتُحصَّل فورًا أو عند تأكيد المورّد.استرداد كامل أو جزئي إلى البطاقة نفسها عبر API.
المحافظ الرقميةحسابات محافظ تدعمها البوابة، مثل PayPal أو محفظة هاتف تحمل بطاقة مُرمَّزة.عند إتمام الشراء، بعد موافقة المسافر داخل المحفظة.يعود إلى المحفظة أو البطاقة خلفها عبر البوابة.
تحويل بنكييحوّل المسافر أو الوكيل المال إلى حسابك البنكي وتُسجَّل الدفعة على الحجز.بعد أيام؛ ينتظر الحجز حتى يؤكد فريقك الاستلام.يُسدَّد بتحويل، خارج البوابة.
ادفع لاحقًايتم الحجز الآن ويُدفع لاحقًا؛ ويسجّل فريقك الدفعة عند وصولها.بعد الحجز، عندما يدفع المسافر.يُعاد فقط ما دُفع فعلًا.
محفظة أو ائتمان وكيل B2Bيدفع الوكلاء الفرعيون من رصيد يشحنونه مسبقًا أو من حد ائتمان تمنحه لهم.يُخصم عند الحجز؛ وتُسوّى العربونات والائتمان وفق شروطك.يُرد إلى رصيد الوكيل.

التحويل البنكي وادفع لاحقًا ورصيد المحفظة خيارات تسوية في المنصة نفسها وليست بوابات. تُشرح أرصدة الوكلاء وحدود الائتمان في صفحة محفظة الوكيل B2B، والمدفوعات البنكية في صفحة الدفع بالتحويل البنكي.

جاهزة في PHPTRAVELS

واجهات API لبوابات الدفع المربوطة مسبقًا

هذه البوابات مربوطة بالفعل مع PHPTRAVELS. تفتح حساب تاجر لدى المزوّد، وتدخل مفاتيح API في لوحة الإدارة، وتختبر في بيئته التجريبية ثم تنتقل إلى التشغيل. القائمة هي القائمة الحية من دليل التكاملات لدينا.

الرسوم وموافقة التاجر تُتفق عليها مع شركة الدفع وليس مع PHPTRAVELS. يمكن إضافة بوابة غير مدرجة هنا على شكل تكامل API مخصص، وتشرح صفحة تكامل بوابات الدفع كيف تُعدّ كل بوابة.

الأمان

إبعاد بيانات البطاقات عن نظامك

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

  • لا تخزّن أرقام البطاقات أبدًا

    تذهب بيانات البطاقة إلى البوابة التي تعيد رمزًا أو معرّف دفعة. تحتفظ قاعدة بياناتك بهذا المرجع فقط، لا برقم البطاقة ولا برمز الأمان.

  • الحقول المستضافة وإعادة التوجيه تقلّص نطاق PCI DSS

    ينطبق PCI DSS على كل من يتعامل مع بيانات البطاقات. حين يكون نموذج البطاقة صفحة البوابة أو حقولًا مضمّنة منها يقلّ كثيرًا ما يدخل من نظامك في النطاق. ويؤكد المصرف المُحصِّل (acquirer) لديك أي تقييم ذاتي ينطبق عليك.

  • Webhooks يُتحقق منها بالتوقيع

    يحمل كل Webhook توقيعًا مصنوعًا بسر مشترك. يعيد خادمك حسابه ويرفض أي حدث لا يطابق، فلا يستطيع أحد تزوير حجز مدفوع.

  • المفاتيح السرية تبقى على الخادم

    لا يتلقى المتصفح سوى مفتاح عام. أما المفتاح السري الذي ينشئ المدفوعات والمستردات فيبقى في إعدادات خادمك، ويحمل كل طلب مفتاح تكرار آمن (idempotency) كي لا تؤدي إعادة المحاولة إلى خصم مرتين.

webhook.php
 1$payload   = file_get_contents("php://input"); 2$signature = $_SERVER["HTTP_X_SIGNATURE"] ?? ""; 3$expected  = hash_hmac("sha256", $payload, $webhookSecret); 4 5if (!hash_equals($expected, $signature)) { 6    http_response_code(400); exit;      // reject 7} 8$event = json_decode($payload, true); 9if (alreadyHandled($event["id"])) exit; // repeat delivery10updateBooking($event["data"]["metadata"]["booking_ref"], $event["type"]);

مثال عام. أسماء الترويسات وطريقة التوقيع تتبعان البوابة التي تختارها.

PHPTRAVELS برنامج مستضاف ذاتيًا، لذا يُقيَّم الامتثال لـ PCI DSS لنشاطك التجاري وخادمك، لا للبرنامج وحده.

شاهد حجزًا يُدفع ويُحصَّل ويُسترد

احجز رحلة في العرض التجريبي المباشر وتابع الدفعة في لوحة الإدارة. وفي خطة Enterprise تمنحك PHPTRAVELS أيضًا REST API وWebhooks خاصة بك لتطبيقاتك وشركائك.

تخطط للطيران أيضًا؟ تشرح صفحة API الطيران جانب المورّد، وتسرد واجهات API للسفر كل واجهة API تربطها PHPTRAVELS.

جرّب العرض التجريبي المباشرقارن الخططاقرأ وثائق المطورين

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

واجهة API لبوابة الدفع: أسئلة بائعي السفر

تحدّث مع المبيعات

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

البوابة هي الجزء الذي يتحدث معه موقعك: تجمع البطاقة بأمان وتمرّر الطلب. أما المعالج فينقل المعاملة عبر شبكات البطاقات إلى البنك المُصدر. ويقدم كثير من المزوّدين الاثنين خدمةً واحدة.

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

التفويض يحجز المبلغ على بطاقة المسافر، والتحصيل يأخذه. وفصلهما يتيح لك الخصم فقط بعد تأكيد المورّد للحجز، وإلغاء الحجز المالي إن لم يؤكد.

في مناطق كثيرة، منها المنطقة الاقتصادية الأوروبية والمملكة المتحدة، تُشترط المصادقة القوية للعميل لمعظم مدفوعات البطاقات عبر الإنترنت، و3-D Secure هو الطريقة التي تستوفي بها البطاقات ذلك. تتولى واجهة API في البوابة التحدي، وينتظر مسار الحجز لديك النتيجة.

ليس وحدها. استخدام الحقول المستضافة أو صفحة الدفع في البوابة يُبقي بيانات البطاقة بعيدًا عن خادمك ويقلّص نطاق PCI DSS لديك، لكن عليك إتمام التقييم الذي يطلبه المصرف المُحصِّل.

نعم، إذا كانت البوابة تدعم الاسترداد الجزئي، وهو ما تفعله معظم بوابات البطاقات. ترسل استردادًا بمبلغ أقل مقابل الدفعة الأصلية، مثل السعر ناقص رسوم الإلغاء.

لا. تفتح حساب تاجر لدى البوابة التي تختارها وتتفق معها على رسومها. تربط PHPTRAVELS منصة الحجز لديك بذلك الحساب عبر مفاتيح API التي تدخلها في لوحة الإدارة.

نعم. يمكن إضافة أي بوابة لها API موثّقة كتكامل مخصص، ولأن الشيفرة المصدرية مضمّنة يستطيع مطوّروك توسيع مسار الدفع أيضًا.

واصل الاستكشاف

المزيد عن المنصة