決済フロー

オンライン予約で受け付ける支払い方法は、ホテルが管理パネルで決定します。予約エンジンはその一覧を表示し、支払い方法ごとに異なる処理を行います。このガイドでは、4つの支払い方法とそれぞれで必要な処理を説明します。

支払い方法を一覧表示する#

ターミナル

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 セキュアフォーム、window.location によるリダイレクトスクリプト、または埋め込み型のチェックアウトフォーム（例：iyzico）のいずれかになります。このフラグメントは解析せず、決済ページにそのまま出力してください。ゲストはプロバイダー側で決済を完了し、指定した returnUrl に戻ります。結果は URL に付加されるクエリパラメーターで通知されます（sonuc=1 成功、sonuc=0 失敗）。自社の注文番号（orderID）は決済レコードと一緒に保存されるため、戻ってきた時点で自社のレコードと照合し、決済が成功した場合にのみ予約を送信してください。

フィールド	備考
`totalPrice`	カートの合計と一致している必要があります。この金額がプロバイダーに送られます。
`orderID`	一意である必要があります。予約の `ID` を使うと照合が容易になります。
`countryID`	国一覧の `id`。
`baskets[]`	客室またはオプションごとに1行。`id` は客室タイプ／パッケージの ID、`piece` は数量、`price` は単価です。

バーチャル POS 情報を直接使用する#

HMS の決済ページではなく自社のサーバーからプロバイダーに接続したい場合は、バーチャル POS 情報エンドポイントから加盟店 ID、キー、プロバイダーコードを取得できます。これらは機密情報です。サーバー側でのみ使用し、この方式を採用する前に HMS と合意してください。

決済後の処理#

タイプ 10 では、決済が確認された後に予約を送信してください。決済に失敗した場合は送信しないでください。
タイプ 3 では、予約をすぐに送信してください。入金があった時点で、ホテルが管理パネルで振込を記録します。
予約送信の Total.amountAfterTaxes は、請求済みまたは請求予定の金額と一致している必要があります。

最終更新: 2026年9月21日誤りを見つけましたか？お知らせください