Flujo de pago

El hotel decide en el panel qué tipos de pago acepta para las reservas online. El motor de reservas muestra esa lista y sigue un camino distinto para cada tipo. Esta guía describe los cuatro tipos de pago y qué hacer en cada uno.

Obtén la lista de tipos de pago#

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

Tipo 1 · Pago en el hotel#

No hay ningún paso adicional. Puedes llamar al endpoint para obtener una confirmación:

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

Tipo 3 · Transferencia bancaria#

Obtén las cuentas bancarias que el hotel ha habilitado para la venta online y muéstraselas al huésped:

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 no hay ninguna cuenta configurada, se devuelve bank_info_is_not_found; en ese caso, oculta este tipo en la lista.

Tipo 9 · Tarjeta de crédito#

El endpoint solo te indica que hay que pedir los datos de la tarjeta:

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

Recoge los datos de la tarjeta en tu propio formulario y, al enviar la reserva, inclúyelos en el campo PaymentCard de cada elemento 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"
    }
}

Tipo 10 · Pago online#

Inicia una sesión de pago con los datos del huésped y de la cesta. Todos los campos son obligatorios; si falta alguno, se indica con required_input_info_not_submitted y 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 es un fragmento HTML que redirige al proveedor: muéstralo tal cual en tu página de pago
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>"
}

El code devuelto es un fragmento HTML: según el proveedor de POS virtual del hotel, es un formulario 3D Secure que se envía automáticamente, un script de redirección window.location o un formulario de pago integrado (p. ej., iyzico). Muestra el fragmento tal cual en tu página de pago; no intentes analizarlo. El huésped completa el pago en el proveedor y vuelve a tu returnUrl; el resultado se indica con parámetros de consulta añadidos a esa URL (sonuc=1 éxito, sonuc=0 error). Tu número de pedido (orderID) se guarda con el registro del pago; cuando el huésped vuelva, relaciónalo con tu propio registro y envía la reserva solo si el pago se ha completado.

Uso directo de los datos del POS virtual#

Si quieres conectarte al proveedor desde tu propio servidor en lugar de usar la página de pago de HMS, el endpoint de datos del POS virtual devuelve el ID de comercio, las claves y el código del proveedor. Son datos secretos: úsalos solo en el servidor y acuerda antes este enfoque con HMS.

Después del pago#

• Con el tipo 10, envía la reserva después de que se confirme el pago; si el pago falla, no la envíes.
• Con el tipo 3, envía la reserva de inmediato; el hotel registra la transferencia en el panel cuando la recibe.
• Al enviar la reserva, Total.amountAfterTaxes debe ser igual al importe cobrado o pendiente de cobro.