Thanh toán

Liệt kê các hình thức thanh toán mà khách sạn chấp nhận cho đặt phòng trực tuyến và bắt đầu bước thanh toán cho hình thức đã chọn. Việc cần làm với từng hình thức được mô tả trong hướng dẫn Luồng thanh toán.

GET/external/online/payment/typeLiệt kê hình thức thanh toán GET/external/payment/companyThông tin POS ảo POST/external/online/payment/type/{paymentType}Bắt đầu bước thanh toán

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

GET/external/online/payment/type

Xác thực: Authorization: Bearer

Trả về các hình thức thanh toán mà khách sạn đã bật cho bán trực tuyến. ID hình thức cố định: 1 thanh toán tại khách sạn, 3 chuyển khoản ngân hàng, 9 thẻ tín dụng (thông tin thẻ gửi kèm đặt phòng), 10 thanh toán trực tuyến (POS ảo).

Tham số truy vấn

hotelIDintegerbắt buộc

ID khách sạn.

Phản hồi

200 Thành công.

Yêu cầu

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

const res = await fetch("https://test.hms.gen.tr/external/online/payment/type?hotelID=1000", {
  headers: {
    "Authorization": `Bearer ${process.env.HMS_TOKEN}`
  }
});
const data = await res.json();

$ch = curl_init('https://test.hms.gen.tr/external/online/payment/type?hotelID=1000');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('HMS_TOKEN'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Phản hồi · 200

{
    "success": true,
    "count": 3,
    "items": [
        {
            "title": "Thanh toán tại khách sạn",
            "title_translate": "odeme.otelde_odeme",
            "typeID": 1
        },
        {
            "title": "Chuyển khoản ngân hàng",
            "title_translate": "odeme.havale",
            "typeID": 3
        },
        {
            "title": "Thanh toán thẻ trực tuyến",
            "title_translate": "odeme.online_odeme",
            "typeID": 10
        }
    ]
}

Thông tin POS ảo#

GET/external/payment/company

Xác thực: Authorization: Bearer

Trả về nhà cung cấp POS ảo và thông tin merchant của khách sạn. Chỉ cần khi bạn tích hợp trực tiếp với nhà cung cấp ở phía mình; luồng tiêu chuẩn dùng POST …/payment/type/10. Phản hồi chứa thông tin bí mật; chỉ giữ ở phía máy chủ.

Tham số truy vấn

hotelIDintegerbắt buộc

ID khách sạn.

Phản hồi

200 Thành công.

Phản hồi lỗi

200 hotel_company_info_could_not_found — khách sạn chưa cấu hình POS ảo.

Yêu cầu

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

const res = await fetch("https://test.hms.gen.tr/external/payment/company?hotelID=1000", {
  headers: {
    "Authorization": `Bearer ${process.env.HMS_TOKEN}`
  }
});
const data = await res.json();

$ch = curl_init('https://test.hms.gen.tr/external/payment/company?hotelID=1000');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('HMS_TOKEN'),
    ],
]);
$data = json_decode(curl_exec($ch), true);

Phản hồi · 200

{
    "success": true,
    "paymentCompany": {
        "merchant_id": "4000****",
        "store_key": "********",
        "terminal_no": "VP00****",
        "user": "demo_api",
        "password": "********",
        "max_installment": 6,
        "company_id": 3,
        "company_code": "iyzico",
        "company_name": "iyzico"
    }
}

Bắt đầu bước thanh toán#

POST/external/online/payment/type/{paymentType}

Xác thực: Authorization: Bearer · Nội dung: application/json

Trả về việc cần làm cho hình thức thanh toán đã chọn. Hình thức 1 và 9 chỉ cần hotelID; hình thức 3 liệt kê các tài khoản ngân hàng; với hình thức 10, thanh toán được khởi tạo bằng thông tin khách và giỏ hàng, và code (HTML) trả về được hiển thị trên trang của khách để chuyển sang màn hình thanh toán của nhà cung cấp.

Tham số đường dẫn

paymentTypeintegerbắt buộc

ID hình thức thanh toán.

13910

Nội dung yêu cầu

hotelIDintegerbắt buộc

ID khách sạn.

totalPricedecimal

Bắt buộc với hình thức 10. Tổng số tiền cần thu.

orderIDstring

Bắt buộc với hình thức 10. Số đơn hàng/đặt phòng của bạn.

returnUrlstring

Bắt buộc với hình thức 10. URL mà khách quay lại sau khi thanh toán.

name / surname / email / phonestring

Bắt buộc với hình thức 10. Thông tin người thanh toán.

city / addressstring

Bắt buộc với hình thức 10. Địa chỉ xuất hóa đơn.

countryIDinteger

Bắt buộc với hình thức 10. id từ danh sách quốc gia.

baskets[]object[]

Bắt buộc với hình thức 10, ít nhất một mục. Mỗi mục: id, name, piece, price.

Phản hồi

200 Hình thức 10: code chứa một đoạn HTML chuyển khách sang nhà cung cấp thanh toán (tùy nhà cung cấp, đó là một form tự động gửi, một script window.location hoặc một form thanh toán nhúng). Hãy hiển thị nguyên trạng đoạn này trong trình duyệt của khách. Với các hình thức khác, trường message cho biết việc cần làm.

Phản hồi lỗi

200 required_input_info_not_submitted (+ errors[]) — thiếu trường với hình thức 10; country_info_sent_incorrectly — countryID không hợp lệ; there_is_missing_info_in_the_shopping_cart — thiếu trường trong một mục giỏ hàng; bank_info_is_not_found — chưa cấu hình tài khoản ngân hàng cho hình thức 3.
404 paymentType không xác định.

Yêu cầu

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,
    "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": "Phòng Tiêu chuẩn · Bao gồm bữa sáng",
            "piece": 1,
            "price": 1930
        },
        {
            "id": 12,
            "name": "Bữa tối",
            "piece": 1,
            "price": 400
        }
    ]
}'

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,
      "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": "Phòng Tiêu chuẩn · Bao gồm bữa sáng",
              "piece": 1,
              "price": 1930
          },
          {
              "id": 12,
              "name": "Bữa tối",
              "piece": 1,
              "price": 400
          }
      ]
  })
});
const data = await res.json();

$ch = curl_init('https://test.hms.gen.tr/external/online/payment/type/10');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('HMS_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'hotelID' => 1000,
        'totalPrice' => 2330,
        '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' => 'Phòng Tiêu chuẩn · Bao gồm bữa sáng',
                'piece' => 1,
                'price' => 1930,
            ],
            [
                'id' => 12,
                'name' => 'Bữa tối',
                'piece' => 1,
                'price' => 400,
            ],
        ],
    ]),
]);
$data = json_decode(curl_exec($ch), true);

Phản hồi · 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>"
}

Phản hồi · 200 (hình thức 3, chuyển khoản ngân hàng)

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

Phản hồi · 200 (hình thức 1 / hình thức 9)

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

Cập nhật lần cuối: 21 tháng 9, 2026Phát hiện lỗi? Hãy cho chúng tôi biết