ขั้นตอนการชำระเงิน

โรงแรมเป็นผู้กำหนดในแผงควบคุมว่าจะรับการชำระเงินประเภทใดบ้างสำหรับการจองออนไลน์ ระบบจองห้องพักจะแสดงรายการนั้นและดำเนินการต่างกันไปตามแต่ละประเภท คู่มือนี้อธิบายการชำระเงินทั้งสี่ประเภทและสิ่งที่ต้องทำในแต่ละประเภท

แสดงรายการประเภทการชำระเงิน#

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 คือส่วนย่อย HTML ที่ส่งต่อไปยังผู้ให้บริการ: แสดงผลตามที่ได้รับบนหน้าชำระเงินของคุณ
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 ซึ่งขึ้นอยู่กับผู้ให้บริการ Virtual POS ของโรงแรม อาจเป็นฟอร์ม 3D Secure ที่ส่งอัตโนมัติ สคริปต์เปลี่ยนเส้นทางด้วย window.location หรือฟอร์มชำระเงินแบบฝัง (เช่น iyzico) ให้แสดงผลส่วนย่อยนี้ตามที่ได้รับบนหน้าชำระเงินของคุณ และอย่าพยายามแยกวิเคราะห์ ผู้เข้าพักจะชำระเงินให้เสร็จที่ผู้ให้บริการแล้วกลับมาที่ returnUrl ของคุณ โดยผลลัพธ์จะแจ้งผ่านพารามิเตอร์คิวรีที่ต่อท้าย URL (sonuc=1 สำเร็จ, sonuc=0 ไม่สำเร็จ) หมายเลขคำสั่งซื้อของคุณ (orderID) จะถูกบันทึกไว้กับรายการชำระเงิน เมื่อผู้เข้าพักกลับมา ให้จับคู่กับรายการของคุณเอง และส่งการจองเฉพาะเมื่อชำระเงินสำเร็จเท่านั้น

การใช้ข้อมูล Virtual POS โดยตรง#

หากต้องการเชื่อมต่อกับผู้ให้บริการจากเซิร์ฟเวอร์ของคุณเองแทนการใช้หน้าชำระเงินของ HMS เอนด์พอยต์ข้อมูล Virtual POS จะส่งคืน merchant ID คีย์ และรหัสผู้ให้บริการ ข้อมูลเหล่านี้เป็นความลับ ให้ใช้เฉพาะฝั่งเซิร์ฟเวอร์ และตกลงแนวทางนี้กับ HMS ก่อน

หลังการชำระเงิน#

• สำหรับประเภท 10 ให้ส่งการจองหลังจากยืนยันการชำระเงินแล้ว และอย่าส่งการจองเมื่อการชำระเงินไม่สำเร็จ
• สำหรับประเภท 3 ให้ส่งการจองทันที โรงแรมจะบันทึกการโอนเงินในแผงควบคุมเมื่อได้รับเงิน
• ในการส่งการจอง Total.amountAfterTaxes ต้องเท่ากับจำนวนเงินที่เรียกเก็บแล้วหรือที่จะเรียกเก็บ