支付流程

酒店在后台决定在线预订接受哪些支付方式。预订引擎展示该列表，并针对每种方式执行不同的流程。本指南介绍四种支付方式及各自的处理方法。

列出支付方式#

终端

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`	信用卡（担保）	卡信息放在 `PaymentCard` 中随预订发送到 HMS，由酒店从卡上扣款。
`10`	在线支付（虚拟 POS）	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"
}

请在您自己的表单中收集卡信息，并在预订推送中每个 RoomStays 项的 PaymentCard 字段中发送：

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 片段：视酒店的虚拟 POS 服务商而定，可能是自动提交的 3D Secure 表单、window.location 跳转脚本或内嵌支付表单（例如 iyzico）。请在支付页面上原样渲染该片段，不要尝试解析。客人在服务商处完成支付后返回您的 returnUrl，支付结果通过附加在该地址上的查询参数告知（sonuc=1 成功，sonuc=0 失败）。您的订单号（orderID）会随支付记录一起保存；客人返回时，请将其与您自己的记录对应，并且仅在支付成功时推送预订。

字段	说明
`totalPrice`	必须等于购物车合计；该金额将提交给支付服务商。
`orderID`	必须唯一。使用预订的 `ID` 便于对账。
`countryID`	国家列表中的 `id`。
`baskets[]`	每个房间或附加服务一行。`id` 为房型/套餐 ID，`piece` 为数量，`price` 为单价。

直接使用虚拟 POS 信息#

如果您希望不经过 HMS 的支付页面，而是从自己的服务器直接对接支付服务商，虚拟 POS 信息端点会返回商户 ID、密钥和服务商代码。这些都是机密信息：只能在服务端使用，并且需事先与 HMS 商定采用此方式。

支付之后#

方式 10：在支付确认之后再推送预订；支付失败时不要推送。
方式 3：立即推送预订；转账到账后，由酒店在后台登记。
在预订推送中，Total.amountAfterTaxes 必须等于已收或应收的金额。

最后更新: 2026年9月21日发现错误？请告诉我们