Tutorials

On this page we collected some main use cases you might face when implementing an application on top of the hetras API. Based on these best practices we hope to get you on track fast.

  1. Booking Process of an Internet Booking Engine
  2. Payment Handling when creating a new booking

Booking Process of an Internet Booking Engine (IBE)

The flow of a standard booking engine is loading all available locations, then requesting the rates for available rooms for a specific hotel and guest stay details and finally creating the booking for the selected room type and rate combination. In this tutorial you will be guided through this process and see which API calls you are required to execute.

The following screenshot is taken from the standard Internet Booking Engine available by hetras to be integrated into any customer website.

Plan your stay

1. Load available locations

To fill a dropdown or to create a map with all available hotels pinned you would need to load all available hotels first. This will be done using the hotels endpoint.

The response for our demo tenant will look like following
< Toggle response body >

[
{
“hotel_id”: 83,
“name”: “Automated Test Hotel 01”,
“street”: “Gartenstrasse 25”,
“city”: “Test City 01”,
“postal_code”: “12345”,
“state”: “Bavaria”,
“country”: “DE”,
“url”: “www.hetras.com”,
“latitude”: “45.361607”,
“longitude”: “25.323809”,
“desc”: “Hotel description 01”,
“email”: “support@hetras.com”,
“phone”: “+49897167180”,
“fax”: “+498971671815”
},
{
“hotel_id”: 84,
“name”: “Automated Test Hotel 02”,
“street”: “Gartenstrasse 25”,
“city”: “Test City 02”,
“postal_code”: “12345”,
“state”: “Bavaria”,
“country”: “DE”,
“url”: “www.hetras.com”,
“latitude”: “45.361607”,
“longitude”: “25.323809”,
“desc”: “Hotel description 02”,
“email”: “support@hetras.com”,
“phone”: “+49897167180”,
“fax”: “+498971671815”
}
]

2. Request rates for available rooms

Based on the input of the booker you need to load offers for available rooms using the rates endpoint.

Specifying the channelCode is mandatory. To get offers for all rateplans to be sold via the website you would need to specify ‘WEB’ for our demo tenant. To get offers for specific negotiated or promotional rates you also need to set the appropriate rate plan code.

A response for a requested stay from March 25th to March 27th for one guest and one room for our demo tenant could look like following
< Toggle response body >

{
“hotel_id”: 83,
“hotel_name”: “Automated Test Hotel 01”,
“arrival_date”: “2015-03-25”,
“departure_date”: “2015-03-27”,
“rate_plans”: [
{
“code”: “STD01”,
“name”: “Standard01”,
“description”: “Rateplan Standard in cheap price category. Available for all RoomTypes coming without breakfast.”
}
],
“room_offers”: [
{
“room”: {
“type”: “EZ”,
“name”: “Single Room”,
“description”: “Single Room with full bathroom.”
},
“offers”: [
{
“rate_plan_code”: “STD01”,
“adults”: 1,
“children”: 0,
“currency”: “EUR”,
“rate”: “160.00”,
“included_tax”: “25.54”,
“excluded_tax”: “0.00”,
“rates”: [
{
“start_date”: “2015-03-25”,
“end_date”: “2015-03-27”,
“element_type”: “UnitType”,
“element_code”: “EZ”,
“rate_amount”: “80.00”,
“tax_amount_included”: “12.77”,
“tax_amount_excluded”: “0.00”
}
],
“guarantee_types”: {
“minimum”: “Deposit”,
“accepted”: [
“Deposit”,
“GuaranteeToCreditCard”,
“GuaranteeToGuestAccount”,
“GuaranteeByTravelAgent”,
“GuaranteeByCompany”,
“PM6Hold”,
“PM4Hold”,
“Prepayment”
]
},
“cancellation_policies”: [
{
“description”: “You may change or cancel the reservation before 6:00pm the day before your scheduled arrival date (local time). Payment is required at time of booking.”,
“fee”: “80.00”,
“fee_date”: “2015-03-25T18:00:00”
}
]
}
]
},
{
“room”: {
“type”: “DZD”,
“name”: “Double Room with shower”,
“description”: “Double Room with shower.”
},
“offers”: [
{
“rate_plan_code”: “STD01”,
“adults”: 1,
“children”: 0,
“currency”: “EUR”,
“rate”: “200.00”,
“included_tax”: “31.93”,
“excluded_tax”: “0.00”,
“rates”: [
{
“start_date”: “2015-03-25”,
“end_date”: “2015-03-27”,
“element_type”: “UnitType”,
“element_code”: “DZD”,
“rate_amount”: “100.00”,
“tax_amount_included”: “15.97”,
“tax_amount_excluded”: “0.00”
}
],
“guarantee_types”: {
“minimum”: “Deposit”,
“accepted”: [
“Deposit”,
“GuaranteeToCreditCard”,
“GuaranteeToGuestAccount”,
“GuaranteeByTravelAgent”,
“GuaranteeByCompany”,
“PM6Hold”,
“PM4Hold”,
“Prepayment”
]
},
“cancellation_policies”: [
{
“description”: “You may change or cancel the reservation before 6:00pm the day before your scheduled arrival date (local time). Payment is required at time of booking.”,
“fee”: “200.00”,
“fee_date”: “2015-03-25T18:00:00”
}
]
}
]
}
]
}

Now you can display the offers for the Single Room and the Double Room with shower and the booker can chose the preferred accomodation.

3. Select offer and create booking

Let´s assume the booker decided to book two Single Rooms with the Standard01 rate. To create the booking you would need to use the create booking endpoint.

The body of the POST would need to look like following
< Toggle request body >

Important to know when creating a booking:

  1. A multi room booking with rooms set to a value greater than 1 need to have the same number of guests, the same room type and the same rate. If you want to support the shopping cart concept and allow the booker to create bookings for different room and rate combinations, you would need to create multiple bookings at hetras and return multiple confirmation ids to the booker or create your own external_id and set it to all new bookings. Currently we do not support transaction management to support the all or nothing handling for multiple bookings.
  2. You would at least need to set the guarantee to the minimum guarantee type defined in the rates response. In our example this is Deposit. This guarantee defines what the hotel expects as a minimum. A higher level guarantee type from the list of accepted guarantee types is always allowed.
  3. Based on the guarantee type additional information can be required to be sent along with the booking request. E.g. for a GuaranteeToCreditCard or Prepayment booking you would also need to provide the credit_card or a token. More information on how to fill in the guarantee object in the body of create booking request can be found in the Payment Handling tutorial.

Payment Handling when creating a new booking

If you create a booking for a rateplan that has either GuaranteeToCreditCard or Prepayment as minimum guarantee type, you should also provide a token in the request body.

Most likely the hotel is integrated with a payment provider and you are using their hosted payment page. When tokenizing a credit card most payment providers just run the Luhn algorithm to check a credit card number. This only tells you that the credit card number is valid for the specified card type, but you don´t know if the card can really be charged. To ensure a credit card is valid and can also be charged you need to ask the payment provider for an authorization. Some support even the authorization of a zero amount like e.g. SixPay. For others you would need to ask for at least an amount of 1.

The following flow illustrates the payment handling of the hetras Hotel Management System when a new reservation is created.

Payment Flow in hetras

Filling out the guarantee object

If you do not specify any guarantee_type in the request body, the reservation will be created using the minimum guarentee type defined on the rate.

For every new booking you can only set the guarantee object for the request body without providing any payment data. The object would then look like this:


"guarantee" : {
	"guarantee_type" : "GuaranteeToCreditCard"
}

Please note:
hetras will accept reservations with guarantee type set to GuaranteeToCreditCard or Prepayment even without a token. You might get a warning with the response, but still get the http status code of 201. The hotel staff will be able to see that there is no valid payment information for the reservation and can manually ask for a valid card and put it to the reservation later. This is additional work for the hotel staff that can be avoided!

You can also just provide a token without any authorization details. As you can see in the flow chart above hetras will then do the authorization and capturing of the amount depending on the guarantee type. The guarantee object would look similar like this:


"guarantee" : {
	"guarantee_type" : "Prepayment",
	"token" : {
		"merchant_reference" : "5548a6e2e2b8b",
		"shopper_email" : "somebody@test.com",
		"shopper_reference" : "5548a6e2e2b8b",
		"token_id" : "5750337182079651100"
	}
}

At least for bookings made for a rate plan set to Prepayment an API client ideally already authorizes the amount before creating the booking in hetras and handles any authorization errors itself. The guarantee object would then look like following:


"guarantee" : {
	"guarantee_type" : "Prepayment",
	"token" : {
		"authorization_status" : "Authorized",
		"authorization_expiry_date" : "2016-05-04",
		"authorization_reference" : "XXXXX",
		"authorized_amount" : "100.00",
		"merchant_reference" : "5548a6e2e2b8b",
		"shopper_email" : "somebody@test.com",
		"shopper_reference" : "5548a6e2e2b8b",
		"token_id" : "5750337182079651100"
	}
}

Please note:
The authorization reference is different from one payment provider to the other. For SixPay it is composed out of TxID, a “|” and the AuthorisationCode.