Fluxul de plată

Hotelul stabilește în panou ce tipuri de plată acceptă pentru rezervările online. Motorul de rezervări afișează această listă și urmează un parcurs diferit pentru fiecare tip. Acest ghid prezintă cele patru tipuri de plată și ce trebuie făcut pentru fiecare.

Listați tipurile de plată#

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

Tipul 1 · Plată la hotel#

Nu există niciun pas suplimentar. Puteți apela endpointul pentru a obține o confirmare:

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

Tipul 3 · Transfer bancar#

Preluați conturile bancare activate de hotel pentru vânzarea online și afișați-le oaspetelui:

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

Dacă nu este configurat niciun cont, se returnează bank_info_is_not_found; ascundeți acest tip din listă.

Tipul 9 · Card de credit#

Endpointul vă indică doar că trebuie colectate datele cardului:

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

Colectați datele cardului în propriul formular și trimiteți-le în câmpul PaymentCard al fiecărui element RoomStays la transmiterea rezervării:

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

Tipul 10 · Plată online#

Inițiați o sesiune de plată cu datele oaspetelui și ale coșului. Toate câmpurile sunt obligatorii; un câmp lipsă este semnalat cu required_input_info_not_submitted și 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 este un fragment HTML care face trecerea la furnizor: afișați-l ca atare în pagina de plată
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 returnat este un fragment HTML: în funcție de furnizorul de POS virtual al hotelului, este un formular 3D Secure trimis automat, un script de redirecționare window.location sau un formular de plată încorporat (de ex. iyzico). Afișați fragmentul ca atare în pagina de plată; nu încercați să îl parsați. Oaspetele finalizează plata la furnizor și revine la returnUrl al dumneavoastră; rezultatul este semnalat prin parametrii de interogare adăugați la acesta (sonuc=1 succes, sonuc=0 eșec). Numărul comenzii (orderID) se salvează împreună cu înregistrarea plății; la revenire, asociați-l cu propria înregistrare și transmiteți rezervarea doar dacă plata a reușit.

Utilizarea directă a datelor POS-ului virtual#

Dacă doriți să vă conectați la furnizor de pe propriul server, în locul paginii de plată HMS, endpointul Datele POS-ului virtual returnează ID-ul de comerciant, cheile și codul furnizorului. Acestea sunt date secrete: folosiți-le exclusiv pe server și stabiliți în prealabil această abordare cu HMS.

După plată#

• Pentru tipul 10, transmiteți rezervarea după confirmarea plății; nu transmiteți rezervarea dacă plata a eșuat.
• Pentru tipul 3, transmiteți rezervarea imediat; hotelul înregistrează transferul în panou când acesta sosește.
• La transmiterea rezervării, Total.amountAfterTaxes trebuie să fie egal cu suma încasată sau de încasat.