Alur pembayaran

Hotel menentukan di panel jenis pembayaran apa saja yang diterima untuk reservasi online. Booking engine menampilkan daftar tersebut dan menjalankan alur yang berbeda untuk setiap jenis. Panduan ini membahas keempat jenis pembayaran dan langkah untuk masing-masing.

Tampilkan jenis pembayaran#

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

Jenis 1 · Bayar di hotel#

Tidak ada langkah tambahan. Anda dapat memanggil endpoint untuk mendapatkan konfirmasi:

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

Jenis 3 · Transfer bank#

Ambil rekening bank yang diaktifkan hotel untuk penjualan online dan tampilkan kepada tamu:

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

Jika belum ada rekening yang dikonfigurasi, bank_info_is_not_found dikembalikan; sembunyikan jenis ini dari daftar.

Jenis 9 · Kartu kredit#

Endpoint ini hanya memberi tahu bahwa detail kartu harus dikumpulkan:

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

Kumpulkan detail kartu melalui form Anda sendiri dan kirim di field PaymentCard pada setiap item RoomStays dalam pengiriman reservasi:

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

Jenis 10 · Pembayaran online#

Mulai sesi pembayaran dengan data tamu dan keranjang. Semua field wajib diisi; field yang tidak ada dilaporkan dengan required_input_info_not_submitted dan 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 adalah fragmen HTML yang meneruskan ke penyedia: tampilkan apa adanya di halaman pembayaran Anda
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 yang dikembalikan adalah fragmen HTML: tergantung penyedia virtual POS hotel, isinya berupa form 3D Secure yang terkirim otomatis, script pengalihan window.location, atau form checkout tersemat (mis. iyzico). Tampilkan fragmen tersebut apa adanya di halaman pembayaran Anda; jangan mencoba mengurainya. Tamu menyelesaikan pembayaran di penyedia dan kembali ke returnUrl Anda; hasilnya ditandai dengan parameter kueri yang ditambahkan ke URL tersebut (sonuc=1 berhasil, sonuc=0 gagal). Nomor pesanan Anda (orderID) disimpan bersama record pembayaran; cocokkan dengan record Anda sendiri saat tamu kembali, dan kirim reservasi hanya jika pembayaran berhasil.

Menggunakan detail virtual POS secara langsung#

Jika Anda ingin terhubung ke penyedia dari server Anda sendiri, bukan melalui halaman pembayaran HMS, endpoint detail virtual POS mengembalikan ID merchant, kunci, dan kode penyedia. Data ini bersifat rahasia: gunakan hanya di sisi server dan sepakati pendekatan ini dengan HMS terlebih dahulu.

Setelah pembayaran#

• Untuk jenis 10, kirim reservasi setelah pembayaran dikonfirmasi; jangan kirim jika pembayaran gagal.
• Untuk jenis 3, kirim reservasi segera; hotel mencatat transfer di panel saat dana diterima.
• Dalam pengiriman reservasi, Total.amountAfterTaxes harus sama dengan jumlah yang sudah atau akan ditagih.