جریان پرداخت

هتل در پنل تعیین می‌کند کدام روش‌های پرداخت را برای رزرو آنلاین بپذیرد. موتور رزرو این فهرست را نمایش می‌دهد و برای هر روش مسیر متفاوتی را دنبال می‌کند. این راهنما چهار روش پرداخت و کارهای لازم برای هر کدام را شرح می‌دهد.

فهرست روش‌های پرداخت#

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

{
    "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
        }
    ]
}

روش 1 · پرداخت در هتل#

مرحله اضافه‌ای لازم نیست. در صورت تمایل می‌توانید برای دریافت تأییدیه، اندپوینت را فراخوانی کنید:

{
    "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}'

{
    "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 · کارت اعتباری#

این اندپوینت فقط اعلام می‌کند که باید اطلاعات کارت دریافت شود:

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

اطلاعات کارت را در فرم خودتان دریافت کنید و در فیلد PaymentCard هر آیتم RoomStays در ارسال رزرو بفرستید:

{
    "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 is an HTML fragment that hands over to the provider: render it as-is on your payment page
res.send(paymentPageTemplate({ providerHtml: data.code }));

{
    "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) همراه با رکورد پرداخت ذخیره می‌شود؛ هنگام بازگشت آن را با رکورد خودتان تطبیق دهید و فقط در صورت موفقیت پرداخت، رزرو را ارسال کنید.

استفاده مستقیم از اطلاعات درگاه پرداخت#

اگر می‌خواهید به‌جای صفحه پرداخت HMS از سرور خودتان به ارائه‌دهنده متصل شوید، اندپوینت اطلاعات درگاه پرداخت شناسه پذیرنده، کلیدها و کد ارائه‌دهنده را برمی‌گرداند. این اطلاعات محرمانه‌اند: فقط سمت سرور از آن‌ها استفاده کنید و پیش از هر چیز این رویکرد را با HMS هماهنگ کنید.

پس از پرداخت#

• در روش 10، رزرو را پس از تأیید پرداخت ارسال کنید؛ اگر پرداخت ناموفق بود، رزرو را ارسال نکنید.
• در روش 3، رزرو را بلافاصله ارسال کنید؛ هتل پس از دریافت وجه، انتقال را در پنل ثبت می‌کند.
• در ارسال رزرو، Total.amountAfterTaxes باید با مبلغ دریافت‌شده یا قابل دریافت برابر باشد.