Betaalflow

Het hotel bepaalt in het beheerpaneel welke betaalmethoden het accepteert voor online boekingen. De boekingsmodule toont die lijst en volgt per methode een eigen route. Deze handleiding behandelt de vier betaalmethoden en wat je bij elke methode doet.

Betaalmethoden opvragen#

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

Type 1 · Betalen in het hotel#

Geen extra stap. Je kunt het endpoint aanroepen om een bevestiging te krijgen:

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

Type 3 · Bankoverschrijving#

Haal de bankrekeningen op die het hotel voor online verkoop heeft ingeschakeld en toon ze aan de gast:

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

Is er geen rekening ingesteld, dan krijg je bank_info_is_not_found terug; verberg deze methode dan in de lijst.

Type 9 · Creditcard#

Het endpoint laat alleen weten dat je de kaartgegevens moet opvragen:

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

Verzamel de kaartgegevens in je eigen formulier en stuur ze bij het doorsturen van de boeking mee in het veld PaymentCard van elk RoomStays-item:

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

Type 10 · Online betaling#

Start een betaalsessie met de gegevens van de gast en de winkelmand. Alle velden zijn verplicht; een ontbrekend veld wordt gemeld met required_input_info_not_submitted en 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 is een HTML-fragment dat doorschakelt naar de provider: render het ongewijzigd op je betaalpagina
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>"
}

De teruggegeven code is een HTML-fragment: afhankelijk van de provider van de virtuele POS van het hotel is het een 3D Secure-formulier dat zichzelf verstuurt, een redirectscript met window.location of een ingesloten betaalformulier (bijv. iyzico). Render het fragment ongewijzigd op je betaalpagina; probeer het niet te ontleden. De gast rondt de betaling af bij de provider en keert terug naar je returnUrl; de uitkomst wordt doorgegeven via queryparameters die aan die URL worden toegevoegd (sonuc=1 geslaagd, sonuc=0 mislukt). Je ordernummer (orderID) wordt bij het betaalrecord opgeslagen; koppel het bij terugkeer aan je eigen record en stuur de boeking alleen door als de betaling is geslaagd.

De gegevens van de virtuele POS rechtstreeks gebruiken#

Wil je vanaf je eigen server verbinding maken met de provider in plaats van de betaalpagina van HMS te gebruiken, dan geeft het endpoint gegevens virtuele POS de merchant-ID, sleutels en providercode terug. Dit zijn geheime gegevens: gebruik ze alleen aan de serverkant en stem deze aanpak eerst af met HMS.

Na de betaling#

• Stuur bij type 10 de boeking pas door nadat de betaling is bevestigd; stuur niets door bij een mislukte betaling.
• Stuur bij type 3 de boeking direct door; het hotel registreert de overschrijving in het beheerpaneel zodra die binnenkomt.
• Bij het doorsturen van de boeking moet Total.amountAfterTaxes gelijk zijn aan het afgerekende of nog af te rekenen bedrag.