Luồng thanh toán

Khách sạn quyết định trong bảng quản trị những hình thức thanh toán nào được chấp nhận cho đặt phòng trực tuyến. Công cụ đặt phòng hiển thị danh sách đó và xử lý theo cách riêng cho từng hình thức. Hướng dẫn này trình bày bốn hình thức thanh toán và việc cần làm với từng hình thức.

Liệt kê hình thức thanh toán#

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

Hình thức 1 · Thanh toán tại khách sạn#

Không có bước bổ sung. Bạn có thể gọi endpoint để nhận xác nhận:

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

Hình thức 3 · Chuyển khoản ngân hàng#

Lấy các tài khoản ngân hàng mà khách sạn đã bật cho bán trực tuyến và hiển thị cho khách:

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

Nếu chưa cấu hình tài khoản nào, API trả về bank_info_is_not_found; hãy ẩn hình thức này khỏi danh sách.

Hình thức 9 · Thẻ tín dụng#

Endpoint chỉ cho bạn biết rằng cần thu thập thông tin thẻ:

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

Thu thập thông tin thẻ bằng form của riêng bạn và gửi trong trường PaymentCard của từng mục RoomStays khi gửi đặt phòng:

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

Hình thức 10 · Thanh toán trực tuyến#

Khởi tạo một phiên thanh toán với thông tin khách và giỏ hàng. Tất cả các trường đều bắt buộc; trường bị thiếu được báo bằng required_input_info_not_submitted và 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 là đoạn HTML chuyển khách sang nhà cung cấp: hiển thị nguyên trạng trên trang thanh toán của bạn
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 trả về là một đoạn HTML: tùy nhà cung cấp POS ảo của khách sạn, đó là một form 3D Secure tự động gửi, một script chuyển hướng window.location hoặc một form thanh toán nhúng (ví dụ iyzico). Hãy hiển thị nguyên trạng đoạn HTML này trên trang thanh toán của bạn; đừng cố phân tích nó. Khách hoàn tất thanh toán tại nhà cung cấp và quay lại returnUrl của bạn; kết quả được báo qua các tham số truy vấn nối vào URL đó (sonuc=1 thành công, sonuc=0 thất bại). Số đơn hàng của bạn (orderID) được lưu cùng bản ghi thanh toán; khi khách quay lại, hãy đối chiếu số này với bản ghi của bạn và chỉ gửi đặt phòng nếu thanh toán thành công.

Dùng trực tiếp thông tin POS ảo#

Nếu bạn muốn kết nối với nhà cung cấp từ máy chủ của mình thay vì dùng trang thanh toán của HMS, endpoint thông tin POS ảo trả về ID merchant, các khóa và mã nhà cung cấp. Đây là thông tin bí mật: chỉ dùng ở phía máy chủ và hãy thống nhất cách làm này với HMS trước.

Sau khi thanh toán#

• Với hình thức 10, chỉ gửi đặt phòng sau khi thanh toán được xác nhận; không gửi khi thanh toán thất bại.
• Với hình thức 3, gửi đặt phòng ngay; khách sạn sẽ ghi nhận khoản chuyển khoản trong bảng quản trị khi nhận được tiền.
• Khi gửi đặt phòng, Total.amountAfterTaxes phải bằng số tiền đã thu hoặc sẽ thu.