Ροή πληρωμής

Το ξενοδοχείο αποφασίζει στον πίνακα διαχείρισης ποιους τύπους πληρωμής δέχεται για online κρατήσεις. Η μηχανή κρατήσεων εμφανίζει αυτή τη λίστα και ακολουθεί διαφορετική διαδρομή για κάθε τύπο. Αυτός ο οδηγός καλύπτει τους τέσσερις τύπους πληρωμής και τι κάνετε σε καθέναν.

Λίστα τύπων πληρωμής#

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

Τύπος 1 · Πληρωμή στο ξενοδοχείο#

Δεν απαιτείται επιπλέον βήμα. Μπορείτε να καλέσετε το τελικό σημείο για να λάβετε επιβεβαίωση:

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

Τύπος 3 · Τραπεζικό έμβασμα#

Ανακτήστε τους τραπεζικούς λογαριασμούς που έχει ενεργοποιήσει το ξενοδοχείο για online πωλήσεις και εμφανίστε τους στον επισκέπτη:

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

Αν δεν έχει ρυθμιστεί λογαριασμός, επιστρέφεται bank_info_is_not_found· αποκρύψτε αυτόν τον τύπο από τη λίστα.

Τύπος 9 · Πιστωτική κάρτα#

Το τελικό σημείο απλώς σας ενημερώνει ότι πρέπει να συλλεχθούν τα στοιχεία της κάρτας:

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

Συλλέξτε τα στοιχεία της κάρτας στη δική σας φόρμα και στείλτε τα στο πεδίο PaymentCard κάθε στοιχείου RoomStays της αποστολής κράτησης:

{
    "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 · Online πληρωμή#

Ξεκινήστε μια συνεδρία πληρωμής με τα στοιχεία του επισκέπτη και του καλαθιού. Όλα τα πεδία είναι υποχρεωτικά· ένα πεδίο που λείπει αναφέρεται με 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 }));

{
    "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 Secure με αυτόματη υποβολή, ένα script ανακατεύθυνσης window.location ή μια ενσωματωμένη φόρμα πληρωμής (π.χ. iyzico). Αποδώστε το τμήμα αυτούσιο στη σελίδα πληρωμής σας· μην προσπαθήσετε να το αναλύσετε. Ο επισκέπτης ολοκληρώνει την πληρωμή στον πάροχο και επιστρέφει στο returnUrl σας· το αποτέλεσμα δηλώνεται με παραμέτρους ερωτήματος που προστίθενται σε αυτό (sonuc=1 επιτυχία, sonuc=0 αποτυχία). Ο αριθμός παραγγελίας σας (orderID) αποθηκεύεται μαζί με την εγγραφή πληρωμής· αντιστοιχίστε τον με τη δική σας εγγραφή κατά την επιστροφή και στείλτε την κράτηση μόνο αν η πληρωμή πέτυχε.

Απευθείας χρήση των στοιχείων εικονικού POS#

Αν θέλετε να συνδέεστε στον πάροχο από τον δικό σας διακομιστή αντί για τη σελίδα πληρωμής του HMS, το τελικό σημείο στοιχείων εικονικού POS επιστρέφει το αναγνωριστικό εμπόρου, τα κλειδιά και τον κωδικό του παρόχου. Πρόκειται για μυστικά στοιχεία: χρησιμοποιήστε τα μόνο στον διακομιστή και συμφωνήστε πρώτα αυτή την προσέγγιση με το HMS.

Μετά την πληρωμή#

• Για τον τύπο 10, στείλτε την κράτηση αφού επιβεβαιωθεί η πληρωμή· μην τη στέλνετε αν η πληρωμή απέτυχε.
• Για τον τύπο 3, στείλτε την κράτηση αμέσως· το ξενοδοχείο καταχωρεί το έμβασμα στον πίνακα διαχείρισης όταν φτάσει.
• Στην αποστολή της κράτησης, το Total.amountAfterTaxes πρέπει να ισούται με το ποσό που εισπράχθηκε ή θα εισπραχθεί.