Flux de paiement

L’hôtel choisit dans le panneau les types de paiement qu’il accepte pour les réservations en ligne. Le moteur de réservation affiche cette liste et suit un parcours différent pour chaque type. Ce guide présente les quatre types de paiement et la marche à suivre pour chacun.

Lister les types de paiement#

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 · Paiement à l’hôtel#

Aucune étape supplémentaire. Vous pouvez appeler l’endpoint pour obtenir un accusé de réception :

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

Type 3 · Virement bancaire#

Récupérez les comptes bancaires que l’hôtel a activés pour la vente en ligne et affichez-les au client :

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

Si aucun compte n’est configuré, bank_info_is_not_found est renvoyé ; masquez alors ce type dans la liste.

Type 9 · Carte de crédit#

L’endpoint se contente d’indiquer que les données de carte doivent être collectées :

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

Collectez les données de carte dans votre propre formulaire et envoyez-les dans le champ PaymentCard de chaque élément RoomStays lors de la transmission de la réservation :

{
    "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 · Paiement en ligne#

Ouvrez une session de paiement avec les informations du client et du panier. Tous les champs sont obligatoires ; un champ manquant est signalé par required_input_info_not_submitted et 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 est un fragment HTML qui passe la main au prestataire : affichez-le tel quel sur votre page de paiement
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>"
}

Le code renvoyé est un fragment HTML : selon le prestataire de TPE virtuel de l’hôtel, il s’agit d’un formulaire 3D Secure à soumission automatique, d’un script de redirection window.location ou d’un formulaire de paiement intégré (p. ex. iyzico). Affichez le fragment tel quel sur votre page de paiement, sans chercher à l’analyser. Le client effectue le paiement chez le prestataire, puis revient sur votre returnUrl ; le résultat est indiqué par des paramètres de requête ajoutés à cette URL (sonuc=1 succès, sonuc=0 échec). Votre numéro de commande (orderID) est enregistré avec la transaction ; au retour, rapprochez-le de votre propre enregistrement et ne transmettez la réservation que si le paiement a abouti.

Utiliser directement les informations du TPE virtuel#

Si vous souhaitez vous connecter au prestataire depuis votre propre serveur plutôt que via la page de paiement de HMS, l’endpoint Informations du TPE virtuel renvoie l’identifiant marchand, les clés et le code du prestataire. Ce sont des secrets : utilisez-les uniquement côté serveur et convenez au préalable de cette approche avec HMS.

Après le paiement#

• Pour le type 10, transmettez la réservation après la confirmation du paiement ; ne la transmettez pas si le paiement a échoué.
• Pour le type 3, transmettez la réservation immédiatement ; l’hôtel enregistre le virement dans le panneau à sa réception.
• Lors de la transmission de la réservation, Total.amountAfterTaxes doit être égal au montant encaissé ou à encaisser.