Hotel Bookings

The HotelBooking service manages the complete hotel booking process, from initial search to final confirmation.

Authentication | Authorization

It follows standard UBIO authentication and authorization process, please refer to here for more details.

Common Response Codes

200 OK - Request successful
400 Bad Request - Invalid request parameters
401 Unauthorized - Invalid or missing authentication
403 Forbidden - Valid authentication but insufficient permissions
404 Not Found - Resource not found
500 Server Error - Internal server error

Booking States

A booking can have the following states (BookingState):

started: The booking has been initiated
pending: The booking is in progress or awaiting some inputs
finished: The booking has been completed either successfully or unsuccessfully

Booking Stages

During the process, a booking goes through different stages (BookingStage):

priceCheck: Initial price verification where you get available rooms and rates
priceConfirmed: Price matches what's available on the website. Wait for startBooking stage to proceed with the booking process.
roomSelection: If price doesn't match or you're skipping confirmation (skipConfirmation=true), you must select a priceId from the availableRooms, and make a new request to /Booking/prices/confirm endpoint. Alternatively, you can cancel the booking
startBooking: Beginning of booking process where it is actually executed the process of booking the room based on initial arguments
processingBooking: Processing the booking is a middle stage where it is either awaiting some inputs or processing the booking
finalPriceConsent: Where you are required to confirm the final price of the booking
awaitingTdsChallenge: Where you are required to complete the 3D Secure challenge (from the rendered HTML)
bookingConfirmed: This is the final stage reached when you hace confirmed the booking
failed: The booking has failed

BookingStatus Object

{
  "bookingId": "uuid",
  "clientId": "string",
  "state": "pending",
  "stage": "roomSelection",
  "createdAt": "2024-01-01T00:00:00Z",
  "succeededAt": null,
  "failedAt": null,
  "error": null,
  "availableRooms": [],
  "priceBreakdown": [],
  "finalPrice": null,
  "confirmation": null
}

Get Room Prices

Get initial room prices for a given search criteria. Use requestId (up to 1 hour) from response to confirm availability and price at /Booking/prices/confirm.

Code sample

POST/Booking/prices

curl -X POST 'https://hotels.automationcloud.net/Booking/prices' \
    -H 'Bearer <token>' \
--data '{
  "search": {
    "hotelId": "hotel123",
    "checkIn": "2024-03-01",
    "nights": 2,
    "guests": 2
  }
}'

Success Responses

Status 200

{
  "requestId": "57487287-f002-4ab7-89b4-8386f7cb1b30",
  "result": {
    "hotelId": "f77c096f-6ca2-4b91-8b18-00004ad8429e",
    "checkIn": "2025-02-15",
    "nights": 1,
    "guests": 2,
    "rooms": [
      {
        "name": "Standard Double Room",
        "capacity": 2,
        "rates": [
          {
            "name": "Advance Purchase",
            "baseRate": {
              "value": 57300,
              "currencyCode": "gbp"
            },
            "taxes": [],
            "occupancy": 2,
            "breakfastIncluded": false,
            "refundable": {
              "available": false
            },
            "rule": "default",
            "fees": [],
            "description": "Deposit Required<>Room only rate, inclusive of VAT.",
            "priceId": "c03b53345d2ee51a"
          },
          {
            "name": "Flexible Rate",
            "baseRate": {
              "value": 60000,
              "currencyCode": "gbp"
            },
            "taxes": [],
            "occupancy": 2,
            "breakfastIncluded": false,
            "refundable": {
              "available": true,
              "untilDate": "2025-02-13"
            },
            "rule": "default",
            "fees": [],
            "description": "Guaranteed with Credit Card<>Room only rate, inclusive of VAT and excluding 5% rooms service charge.",
            "priceId": "bcb202f07bb63175"
          }
        ],
        "description": "Large windows overlooking the courtyard or with city views. The perfect urban retreat.",
        "images": [
          {
            "type": "Link",
            "name": "CRS",
            "url": "https://gc.synxis.com//hotel/35787/Images/Room/standard_double.jpg"
          },
          {
            "type": "Link",
            "name": "VScape",
            "url": "https://d321ocj5nbe62c.cloudfront.net/imageRepo/7/0/164/137/931/1._Standard_S.jpg"
          }
        ]
      },
      "..."
    ]
  }
}

List of available rooms with prices

Confirm availability and price

Confirm if the room is available, the price is correct. If room is not available, the response will include the available rooms with new prices (priceIds). When room not available, call this endpoint again with the new bookingPriceId from availableRooms response or cancel the booking.

However, you can also skip price confirmation by setting skipConfirmation=true in the request. This will cause this endpoint to not confirm the price in the website, and respond with all available rooms instead.

Note: You can make a request to this endpoint up to 1 hour for the same requestId, after response from /Booking/prices. Although, in the eventuality of selecting a new priceId from the availableRooms of this endpoint's response, you can use the same requestId in the request.

Code sample

POST/Booking/prices/confirm

curl -X POST 'https://hotels.automationcloud.net/Booking/prices/confirm' \
    -H 'Bearer <token>' \
--data '{
  "bookingPriceId": "price123",
  "requestId": "req123",
  "simulateBooking": false
}'

Success Responses

Status 200

{
  "bookingId": "80c63970-05ae-4920-b7c4-563d27bd63af",
  "clientId": "26c177b8-5233-4f17-92b4-4573ef9f9394",
  "state": "pending",
  "stage": "priceConfirmed",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": null,
  "failedAt": null,
  "error": null,
  "selectedRooms": [
    {
      "name": "Standard Double Room",
      "description": "Queen-size bed and cosy sitting area with walk-in shower. Large windows overlooking the courtyard or with city views. The perfect urban retreat.",
      "images": [
        {
          "type": "Link",
          "name": "Image",
          "url": "https://gc.synxis.com//hotel/35787/Images/Room/standard_double.jpg"
        },
        {
          "type": "Link",
          "name": "Image",
          "url": "https://d321ocj5nbe62c.cloudfront.net/imageRepo/7/0/164/137/931/1._Standard_S.jpg"
        }
      ],
      "rates": [
        {
          "name": "Advance Purchase",
          "description": "Room only rate, inclusive of VAT.",
          "baseRate": {
            "value": 54100,
            "currencyCode": "gbp"
          },
          "priceId": "92653aeb66b5c7b7",
          "taxes": [],
          "breakfastIncluded": false,
          "allInclusive": false,
          "refundable": {
            "available": false
          },
          "rule": "default",
          "fees": []
        }
      ]
    }
  ]
}

Room available (stage is "priceConfirmed"), wait till booking can start (stage is "startBooking")

{
  "bookingId": "80c63970-05ae-4920-b7c4-563d27bd63af",
  "clientId": "26c177b8-5233-4f17-92b4-4573ef9f9394",
  "state": "pending",
  "stage": "roomSelection",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": null,
  "failedAt": null,
  "error": {
    "category": "system",
    "code": "PriceNotFound",
    "message": "Price not found by `bookingPriceId`. Use a different `priceId` from `availableRooms`",
    "object": "error"
  },
  "availableRooms": [
    {
      "name": "Standard Double Room",
      "description": "Queen-size bed and cosy sitting area with walk-in shower. Large windows overlooking the courtyard or with city views. The perfect urban retreat.",
      "images": [
        {
          "type": "Link",
          "name": "Image",
          "url": "https://gc.synxis.com//hotel/35787/Images/Room/standard_double.jpg"
        },
        {
          "type": "Link",
          "name": "Image",
          "url": "https://d321ocj5nbe62c.cloudfront.net/imageRepo/7/0/164/137/931/1._Standard_S.jpg"
        }
      ],
      "rates": [
        {
          "name": "Advance Purchase",
          "description": "Room only rate, inclusive of VAT.",
          "baseRate": {
            "value": 54100,
            "currencyCode": "gbp"
          },
          "priceId": "92653aeb66b5c7b7",
          "taxes": [],
          "breakfastIncluded": false,
          "allInclusive": false,
          "refundable": {
            "available": false
          },
          "rule": "default",
          "fees": []
        },
        {
          "name": "Flexible Rate",
          "description": "Room only rate, inclusive of VAT and excluding 5% rooms service charge.",
          "baseRate": {
            "value": 60000,
            "currencyCode": "gbp"
          },
          "priceId": "bcb202f07bb63175",
          "taxes": [],
          "breakfastIncluded": false,
          "allInclusive": false,
          "refundable": {
            "available": false
          },
          "rule": "default",
          "fees": []
        }
      ]
    }
  ]
}

Booking not available, needing room selection, please notice the error message in JSON

{
  "bookingId": "80c63970-05ae-4920-b7c4-563d27bd63af",
  "clientId": "26c177b8-5233-4f17-92b4-4573ef9f9394",
  "state": "pending",
  "stage": "roomSelection",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": null,
  "failedAt": null,
  "error": null,
  "availableRooms": [
    {
      "name": "Standard Double Room",
      "description": "Queen-size bed and cosy sitting area with walk-in shower. Large windows overlooking the courtyard or with city views. The perfect urban retreat.",
      "images": [
        {
          "type": "Link",
          "name": "Image",
          "url": "https://gc.synxis.com//hotel/35787/Images/Room/standard_double.jpg"
        },
        {
          "type": "Link",
          "name": "Image",
          "url": "https://d321ocj5nbe62c.cloudfront.net/imageRepo/7/0/164/137/931/1._Standard_S.jpg"
        }
      ],
      "rates": [
        {
          "name": "Advance Purchase",
          "description": "Room only rate, inclusive of VAT.",
          "baseRate": {
            "value": 54100,
            "currencyCode": "gbp"
          },
          "priceId": "92653aeb66b5c7b7",
          "taxes": [],
          "breakfastIncluded": false,
          "allInclusive": false,
          "refundable": {
            "available": false
          },
          "rule": "default",
          "fees": []
        },
        {
          "name": "Flexible Rate",
          "description": "Room only rate, inclusive of VAT and excluding 5% rooms service charge.",
          "baseRate": {
            "value": 60000,
            "currencyCode": "gbp"
          },
          "priceId": "bcb202f07bb63175",
          "taxes": [],
          "breakfastIncluded": false,
          "allInclusive": false,
          "refundable": {
            "available": false
          },
          "rule": "default",
          "fees": []
        }
      ]
    }
  ]
}

Response includes all available rooms, must recall this endpoint with the same `requestId` and `bookingPriceId` (one of `priceId` in `availableRooms`)

Get Booking Status

Returns the current status of a booking by its ID.

Code sample

GET/Booking/book/{bookingId}/status

curl -X GET 'https://hotels.automationcloud.net/Booking/book/{bookingId}/status' \
    -H 'Bearer <token>'

Success Responses

Status 200

{
  "bookingId": "80c63970-05ae-4920-b7c4-563d27bd63af",
  "clientId": "2462ca78-8e79-4774-aa10-e89f8f34b4ee",
  "state": "pending",
  "stage": "finalPriceConsent",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": null,
  "failedAt": null,
  "error": null,
  "finalPrice": {
    "price": {
      "value": 54100,
      "currencyCode": "gbp"
    }
  }
}

Current booking status with available information based on stage

Process Booking

Provides inputs for a booking with guest and payment information.

Code sample

POST/Booking/book/{bookingId}

curl -X POST 'https://hotels.automationcloud.net/Booking/book/{bookingId}' \
    -H 'Bearer <token>' \
--data '{
  "details": {
    "mainGuest": {
      "person": {
        "firstName": "John",
        "lastName": "Doe"
      },
      "contact": {
        "email": "john@example.com",
        "phone": "+1234567890"
      }
    }
  },
  "payment": {
    "card": {
      "type": "credit",
      "brand": "visa",
      "expirationDate": "2035-12",
      "name": "John Doe",
      "cvv": "123"
    },
    "person": {
      "title": "mr",
      "firstName": "John",
      "lastName": "Doe"
    },
    "address": {
      "streetName": "123 Main St",
      "city": "Anytown",
      "postcode": "12345",
      "countryCode": "us",
      "countrySubdivision": "ca"
    }
  },
  "panToken": "token123"
}'

Success Responses

Status 200

{
  "bookingId": "80c63970-05ae-4920-b7c4-563d27bd63af",
  "clientId": "2462ca78-8e79-4774-aa10-e89f8f34b4ee",
  "state": "pending",
  "stage": "processingBooking",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": null,
  "failedAt": null,
  "error": null
}

Booking status after initialization

Confirm Booking

Confirms the booking with the existing final price for the booking.

Code sample

POST/Booking/book/{bookingId}/confirm

curl -X POST 'https://hotels.automationcloud.net/Booking/book/{bookingId}/confirm' \
    -H 'Bearer <token>'

Success Responses

Status 200

{
  "bookingId": "80c63970-05ae-4920-b7c4-563d27bd63af",
  "clientId": "2462ca78-8e79-4774-aa10-e89f8f34b4ee",
  "state": "finished",
  "stage": "bookingConfirmed",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": "2025-02-03T12:51:35.927Z",
  "confirmation": {
    "message": "Booking confirmed",
    "reference": "1234567890"
  }
}

Booking status with confirmation details

Cancel Booking

Cancels an active booking.

Code sample

POST/Booking/book/{bookingId}/cancel

curl -X POST 'https://hotels.automationcloud.net/Booking/book/{bookingId}/cancel' \
    -H 'Bearer <token>'

Success Responses

Status 200

{
  "bookingId": "123e4567-e89b-12d3-a456-426614174000",
  "clientId": "2462ca78-8e79-4774-aa10-e89f8f34b4ee",
  "state": "Finished",
  "stage": "Failed",
  "createdAt": "2025-02-03T12:51:35.927Z",
  "succeededAt": null,
  "failedAt": "2025-02-03T12:51:35.927Z",
  "error": {
    "object": "job-error",
    "code": "ServerError",
    "category": "server",
    "message": ""
  }
}

Updated booking status after cancellation

Render 3DSecure of the booking

Get the 3D Secure (challenge) HTML of the booking #3dsecure #3ds #threedsecure #tds

Code sample

GET/Booking/book/{bookingId}/tds

curl -X GET 'https://hotels.automationcloud.net/Booking/book/{bookingId}/tds' \

Success Responses

Status 200

<html>
<head>
<style>
  body { margin: 0; padding: 0; }
</style>
</head>
<body>
  <iframe src='<3DS_CHALLENGE_URL>' width='100%' height='100%' frameborder='0'></iframe>
  <script>
    window.addEventListener('message', event => {
      if (event.data === '3dsecure-finished') {
        // We are done with 3D Secure!
        console.log('3D Secure form closed.');
      }
    });
  </script>
</body>
</html>

HTML content with iframe to render the 3D Secure challenge

Error Responses

Status 400

{
  "status": 400,
  "name": "ClientError",
  "message": "Invalid booking stage",
  "details": {}
}

Booking is not in "awaitingTdsChallenge" stage

# Hotel Bookings

# Authentication | Authorization

# Common Response Codes

# Booking States

# Booking Stages

# BookingStatus Object

# Get Room Prices

# Code sample

# Success Responses

# Confirm availability and price

# Code sample

# Success Responses

# Get Booking Status

# Code sample

# Success Responses

# Process Booking

# Code sample

# Success Responses

# Confirm Booking

# Code sample

# Success Responses

# Cancel Booking

# Code sample

# Success Responses

# Render 3DSecure of the booking

# Code sample

# Success Responses

# Error Responses

Hotel Bookings

Authentication | Authorization

Common Response Codes

Booking States

Booking Stages

BookingStatus Object

Get Room Prices

Code sample

Success Responses

Confirm availability and price

Code sample

Success Responses

Get Booking Status

Code sample

Success Responses

Process Booking

Code sample

Success Responses

Confirm Booking

Code sample

Success Responses

Cancel Booking

Code sample

Success Responses

Render 3DSecure of the booking

Code sample

Success Responses

Error Responses