Ödeme akışı

Otel, online rezervasyonda hangi ödeme tiplerini kabul edeceğini panelden belirler. Rezervasyon motoru bu listeyi gösterir ve seçilen tipe göre farklı bir yol izler. Bu rehber dört ödeme tipini ve her birinde yapılacakları anlatır.

Ödeme tiplerini listeleyin#

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

{
    "success": true,
    "count": 3,
    "items": [
        {
            "title": "Otelde Ödeme",
            "title_translate": "odeme.otelde_odeme",
            "typeID": 1
        },
        {
            "title": "Havale / EFT",
            "title_translate": "odeme.havale",
            "typeID": 3
        },
        {
            "title": "Kredi Kartı ile Online Ödeme",
            "title_translate": "odeme.online_odeme",
            "typeID": 10
        }
    ]
}

Tip 1 · Otelde ödeme#

Ek adım yoktur. İsterseniz uç noktayı çağırıp onay alabilirsiniz:

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

Tip 3 · Havale / EFT#

Otelin online satış için tanımladığı banka hesaplarını alın ve misafire gösterin:

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 Bankası",
            "holder": "Demo Turizm A.Ş.",
            "branchName": "Denizli",
            "branchNumber": "0123",
            "bankAccountNumber": "12345678-5001",
            "iban": "TR00 0001 0001 2345 6789 5001 01"
        }
    ]
}

Tanımlı hesap yoksa bank_info_is_not_found döner; bu tipi listeden gizleyin.

Tip 9 · Kredi kartı#

Uç nokta yalnızca kart bilgisinin istenmesi gerektiğini bildirir:

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

Kart bilgisini kendi formunuzda alın ve rezervasyon aktarımında her RoomStays öğesinin PaymentCard alanında gönderin:

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

Tip 10 · Online ödeme#

Misafir ve sepet bilgileriyle ödeme oturumu açın. Tüm alanlar zorunludur; eksik alan required_input_info_not_submitted ve errors[] ile bildirilir.

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://rezervasyon.example.com/odeme/sonuc",
    "name": "Ayşe", "surname": "Demir",
    "email": "[email protected]", "phone": "05551112233",
    "city": "Denizli", "address": "Kumsal Cad. No: 12", "countryID": 1,
    "baskets": [
      { "id": 2,  "name": "Standart Oda · Kahvaltı Dahil", "piece": 1, "price": 1930.00 },
      { "id": 12, "name": "Akşam Yemeği", "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://rezervasyon.example.com/odeme/sonuc",
    name: "Ayşe", surname: "Demir",
    email: "[email protected]", phone: "05551112233",
    city: "Denizli", address: "Kumsal Cad. No: 12", countryID: 1,
    baskets: [
      { id: 2,  name: "Standart Oda · Kahvaltı Dahil", piece: 1, price: 1930.00 },
      { id: 12, name: "Akşam Yemeği", piece: 1, price: 400.00 }
    ]
  })
});
const data = await res.json();
if (!data.success) throw new Error(data.message + " " + (data.errors || []).join(", "));
// data.code sağlayıcıya yönlendiren HTML parçasıdır: ödeme sayfanıza olduğu gibi basın
res.send(paymentPageTemplate({ providerHtml: data.code }));

{
    "success": true,
    "message": "payment_order_code",
    "code": "<form method=\"post\" action=\"https://sanalpos.saglayici.com/3d\"><input type=\"hidden\" name=\"orderId\" value=\"4811174883\"> … </form><script>document.forms[0].submit()</script>"
}

Dönen code bir HTML parçasıdır: otelin sanal POS sağlayıcısına göre otomatik gönderilen bir 3D Secure formu, window.location ile yönlendiren bir script ya da gömülü bir ödeme formu (örn. iyzico checkout) olabilir. Bu parçayı ödeme sayfanızda olduğu gibi basın; içeriğini ayrıştırmaya çalışmayın. Misafir ödemeyi sağlayıcıda tamamlar ve returnUrl adresinize geri döner; sonuç, adrese eklenen sorgu parametreleriyle (sonuc=1 başarılı, sonuc=0 başarısız) bildirilir. Sipariş numaranız (orderID) ödeme kaydında saklanır; dönüşte kendi kaydınızla eşleştirin ve ancak ödeme başarılıysa rezervasyonu aktarın.

Sanal POS bilgisini doğrudan kullanmak#

Ödemeyi HMS’in ödeme sayfası yerine kendi sunucunuzda sağlayıcıya bağlamak isterseniz sanal POS bilgisi uç noktası mağaza kimliği, anahtar ve sağlayıcı kodunu döner. Bu bilgiler gizlidir; yalnızca sunucu tarafında kullanın ve bu yolu HMS ile görüşerek tercih edin.

Ödeme sonrası#

• Tip 10’da rezervasyonu ödeme onayından sonra aktarın; başarısız ödemede aktarmayın.
• Tip 3’te rezervasyonu hemen aktarın; havale gelince otel panelden tahsilatı işler.
• Rezervasyon aktarımında Total.amountAfterTaxes tahsil edilen/edilecek tutarla aynı olmalıdır.