مسار الدفع

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

عرض أنواع الدفع#

الطرفية

curl "https://test.hms.gen.tr/external/online/payment/type?hotelID=1000" \
  -H "Authorization: Bearer $HMS_TOKEN"

الاستجابة · 200

{
    "success": true,
    "count": 3,
    "items": [
        {
            "title": "Pay at Hotel",
            "title_translate": "odeme.otelde_odeme",
            "typeID": 1
        },
        {
            "title": "Bank Transfer",
            "title_translate": "odeme.havale",
            "typeID": 3
        },
        {
            "title": "Online Card Payment",
            "title_translate": "odeme.online_odeme",
            "typeID": 10
        }
    ]
}

typeID	النوع	ما يحدث
`1`	الدفع في الفندق	لا يوجد تحصيل؛ يُرسَل الحجز مباشرةً.
`3`	التحويل البنكي	تُعرض الحسابات البنكية للفندق، ويُرسَل الحجز بحالة «بانتظار الدفع».
`9`	بطاقة الائتمان (ضمان)	تُرسَل بيانات البطاقة إلى HMS مع الحجز في `PaymentCard`، ويتولى الفندق الخصم من البطاقة.
`10`	الدفع الإلكتروني (نقطة البيع الافتراضية)	تبدأ HMS جلسة دفع، ويُحوَّل النزيل إلى صفحة الدفع لدى المزوّد ثم يعود إلى `returnUrl` الخاص بك.

النوع 1 · الدفع في الفندق#

لا توجد خطوة إضافية. ويمكنك استدعاء نقطة النهاية للحصول على إقرار:

POST …/payment/type/1 → 200

{
    "success": true,
    "message": "payment_at_the_hotel"
}

النوع 3 · التحويل البنكي#

اجلب الحسابات البنكية التي فعّلها الفندق للبيع عبر الإنترنت واعرضها على النزيل:

الطرفية

curl -X POST "https://test.hms.gen.tr/external/online/payment/type/3" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hotelID": 1000}'

الاستجابة · 200

{
    "success": true,
    "message": "payment_by_bank_transfer",
    "banks": [
        {
            "companyName": "Ziraat Bank",
            "holder": "Demo Turizm A.Ş.",
            "branchName": "Denizli",
            "branchNumber": "0123",
            "bankAccountNumber": "12345678-5001",
            "iban": "TR00 0001 0001 2345 6789 5001 01"
        }
    ]
}

إذا لم يُضبط أي حساب، تُعاد bank_info_is_not_found؛ وفي هذه الحالة أخفِ هذا النوع من القائمة.

النوع 9 · بطاقة الائتمان#

تكتفي نقطة النهاية بإبلاغك بضرورة جمع بيانات البطاقة:

POST …/payment/type/9 → 200

{
    "success": true,
    "message": "credit_card_info_should_be_requested"
}

اجمع بيانات البطاقة عبر نموذجك الخاص، وأرسلها في الحقل PaymentCard لكل عنصر من عناصر RoomStays عند إرسال الحجز:

RoomStays[].PaymentCard

{
    "PaymentCard": {
        "CardHolder": {
            "fullname": "Ayşe Demir",
            "address": "Kumsal Cad. No: 12",
            "country": "Türkiye",
            "city": "Antalya"
        },
        "cardNumber": "5571135571135575",
        "expireDate": "0329",
        "cardCode": "MasterCard",
        "seriesCode": "000"
    }
}

النوع 10 · الدفع الإلكتروني#

ابدأ جلسة دفع ببيانات النزيل وسلة الشراء. جميع الحقول إلزامية، ويُبلَّغ عن أي حقل مفقود عبر required_input_info_not_submitted وerrors[].

الطلب

curl -X POST "https://test.hms.gen.tr/external/online/payment/type/10" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hotelID": 1000,
    "totalPrice": 2330.00,
    "orderID": "4811174883",
    "returnUrl": "https://booking.example.com/payment/result",
    "name": "Ayşe", "surname": "Demir",
    "email": "[email protected]", "phone": "05551112233",
    "city": "Denizli", "address": "Kumsal Cad. No: 12", "countryID": 1,
    "baskets": [
      { "id": 2,  "name": "Standard Room · Bed & Breakfast", "piece": 1, "price": 1930.00 },
      { "id": 12, "name": "Dinner", "piece": 1, "price": 400.00 }
    ]
  }'

const res = await fetch("https://test.hms.gen.tr/external/online/payment/type/10", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.HMS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    hotelID: 1000,
    totalPrice: 2330.00,
    orderID: "4811174883",
    returnUrl: "https://booking.example.com/payment/result",
    name: "Ayşe", surname: "Demir",
    email: "[email protected]", phone: "05551112233",
    city: "Denizli", address: "Kumsal Cad. No: 12", countryID: 1,
    baskets: [
      { id: 2,  name: "Standard Room · Bed & Breakfast", piece: 1, price: 1930.00 },
      { id: 12, name: "Dinner", piece: 1, price: 400.00 }
    ]
  })
});
const data = await res.json();
if (!data.success) throw new Error(data.message + " " + (data.errors || []).join(", "));
// data.code مقتطف HTML يحوّل النزيل إلى المزوّد: اعرضه كما هو في صفحة الدفع لديك
res.send(paymentPageTemplate({ providerHtml: data.code }));

الاستجابة · 200

{
    "success": true,
    "message": "payment_order_code",
    "code": "<form method=\"post\" action=\"https://vpos.provider.example/3d\"><input type=\"hidden\" name=\"orderId\" value=\"4811174883\"> … </form><script>document.forms[0].submit()</script>"
}

القيمة المُعادة في code مقتطف HTML: فبحسب مزوّد نقطة البيع الافتراضية لدى الفندق، قد يكون نموذج 3D Secure يُرسَل تلقائيًا، أو سكربت إعادة توجيه عبر window.location، أو نموذج دفع مضمَّنًا (مثل iyzico). اعرض المقتطف كما هو في صفحة الدفع لديك، ولا تحاول تحليله. يُكمل النزيل الدفع لدى المزوّد ثم يعود إلى returnUrl الخاص بك، وتُبلَّغ النتيجة عبر معاملات استعلام تُلحق بهذا العنوان (sonuc=1 نجاح، sonuc=0 فشل). يُحفَظ رقم طلبك (orderID) مع سجل الدفع؛ فطابقه مع سجلك الخاص عند العودة، ولا ترسل الحجز إلا إذا نجح الدفع.

الحقل	ملاحظة
`totalPrice`	يجب أن يساوي إجمالي السلة؛ فهذا المبلغ هو ما يُرسَل إلى المزوّد.
`orderID`	يجب أن يكون فريدًا. واستخدام `ID` الخاص بالحجز يسهّل المطابقة.
`countryID`	قيمة `id` من قائمة الدول.
`baskets[]`	سطر واحد لكل غرفة أو إضافة. `id` هو معرّف نوع الغرفة / الباقة، و`piece` الكمية، و`price` سعر الوحدة.

استخدام بيانات نقطة البيع الافتراضية مباشرةً#

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

بعد الدفع#

في النوع 10، أرسل الحجز بعد تأكيد الدفع، ولا ترسله إذا فشل الدفع.
في النوع 3، أرسل الحجز فورًا؛ وسيسجّل الفندق التحويل في لوحة التحكم عند وصوله.
عند إرسال الحجز، يجب أن تساوي Total.amountAfterTaxes المبلغ المحصَّل أو المقرر تحصيله.

آخر تحديث: 21 سبتمبر 2026هل وجدت خطأً؟ أخبرنا