Booking notification

This endpoint should be implemented by partners connecting to Holidu’s API and willing to have their properties bookable on Holidu.

Holidu will send a request to notify the partners when one of their properties is booked. The partners need to register the booking in their system and confirm the receiving of the booking. There needs to be a unique transaction id for any successful transmitted booking provided by the partner in the response to the request.

❗️
Please only accept bookings if the total price in the booking notification matches the price in your system. Due to some configuration errors or time delays it can be possible to have price differences between your prices and the prices shown on holidu, BUT the customer books the property based on the prices shown on holidu. In order to avoid customer complaints and cancelled bookings, please reject bookings with a wrong price directly.

BookingNotification Request

It is a POST request with the following parameters:

Field	Type	Required	Content
bookingId	string	true	Booking ID created by Holidu
externalId	string	true	Your Identifier + Apartment ID in your system (see example below)
arrival	LocalDate: YYYY-MM-DD	true	When the customer would check in
departure	LocalDate: YYYY-MM-DD	true	When the customer would check out
guests	Array of Guest objects	true	List of guests
gender	string: male female	true	Gender
firstName	string	true	First name
lastName	string	true	Last name
street	string	true	Name of the street
zip	string	true	Zip code
city	string	true	City
country	string: DE, FR, US, GB, etc.	true	Country of the user (ISO 3166-2)
phone	string	true	Phone number
email	string	true	Email address
comment	string	optional	Special request or comment
extraServices	Array of ExtraService objects	optional	List of extra services included in the final price (selected options)
price	Price object	optional	Final price including all the mandatory and selected extra costs but without Tourist Tax
paymentMethod	string: BANK_TRANSFER, INVOICE, VISA, CREDIT_CARD, MAESTRO, PAYPAL, MASTER_CARD, AMERICAN_EXPRESS, JAPAN_CREDIT_BUREAU, DINERS_CLUB, MASTERPASS	true	The payment method selected by the customer
paymentRates	Array of payment rates	optional	The payment rates calculated as per configuration
currency	string: EUR, USD, GBP, etc.	true	User’s currency (ISO 4217)
language	string: de, fr, en, etc.	true	Language that the customer speaks (ISO 639-1)
costs	Array of Mandatory Cost objects	optional	List of mandatory costs pushed to Holidu

Guest object
Each guest is represented by a guest object containing information about him.

Field	Type	Required	Content
age	integer	true	The age of this guest

ExtraService object
Information about selected option or mandatory costs included in the total price.

Field	Type	Required	Content
serviceId	string	true	Id of the service you provide in our API
quantity	integer	true	Quantity selected by the guest
label	string	true	Name of the service you provide

Price object
Price information in both original and user’s currency. They can be the same if the user uses the original currency.

Field	Type	Required	Content
value	number (BigDecimal)	true	Price in user’s currency
currency	string: EUR, USD, GBP, etc.	true	User’s currency (ISO 4217)
originalValue	number (BigDecimal)	true	Price in original currency
originalCurrency	string: EUR, USD, GBP, etc.	true	Original currency (ISO 4217)

Payment rates object

Field	Type	Required	Content
price	Price object	true	Total price due on date
dueDate	string	true	Date on which the payment is due, pattern: yyyy-MM-dd
percentage	number (BigDecimal)	true	Percentage of total price which is due

Cost object

Field	Type	Required	Content
serviceId	String	true	Id of the cost in our API
label	String	true	Name of the cost in our API
description	String	true	Description of the cost
costType	String: MANDATORY_EXCLUDED_FROM_BASE_PRICE	true	Type of cost.
costUnit	String: PER_NIGHT, PER_TWO_NIGHTS, PER_DAY, PER_WEEK, PER_MONTH, PER_STAY, PER_PERSON, PER_PERSON_PER_NIGHT, PER_PERSON_PER_TWO_NIGHTS, PER_PERSON_PER_DAY, PER_PERSON_PER_WEEK, PER_PET, PER_PET_PER_NIGHT, PER_PET_PER_DAY, PER_PET_PER_WEEK, PER_UNIT, PER_PERCENTAGE	true	Unit at which the cost is charged.
pricePerUnit	Price object	true	Price per unit of the cost
totalPrice	Price object	optional	Total price of the cost based on calculations
paymentDueDate	String	true	Date on which the payment is due, pattern: yyyy-MM-dd
paymentTime	String: WITH_BASE_PRICE, ON_ARRIVAL, ON_DEPARTURE, ON_DATE, ON_SITE	true	Time at which the payment for the cost is expected.
maximumCount	integer	true	Maximum count of the cost that is possible
minimumCount	integer	true	Minimum count of the cost that is possible
conditions	Array of Condition object	optional	Conditions that are applicable to the cost. See Condition object below.

Condition object

Field	Type	Required	Content
type	String: PRICE_RANGE, VALIDITY_PERIOD, NUMBER_OF_NIGHTS, NUMBER_OF_PEOPLE, AGE_OF_PERSON	true	The type of condition on which the cost is applied
from	string	true	Start range of the condition
to	string	true	End range of the condition

Example booking notification

{
 "bookingId": "eacf97a4-cba2-4db1-8c02-d69306fc369f",
 "externalId": "PROVIDER-623730",
 "arrival": "2018-12-07",
 "departure": "2018-12-10",
 "guests": [
   {
     "age": 18
   },
   {
     "age": 18
   }
 ],
 "gender": "male",
 "firstName": "Test1 2",
 "lastName": "Test 2 3 4",
 "street": "Teststreet 24",
 "zip": "80992",
 "city": "München",
 "country": "DE",
 "phone": "000000000000",
 "email": "[email protected]",
 "comment": "TEST booking, please cancel",
 "extraServices": [
   {
     "serviceId": "110_fac_xb",
     "providerServiceId":"3344-abba",
     "quantity": 1,   
     "label": "Haustier"
   },
   {
     "serviceId": "111_fac_xb",
     "providerServiceId":"3345-abba",
     "quantity": 2,
     "label": "Bettwäsche"
   }
 ],
 "price": {
   "value": 1820.00,
   "currency": "EUR",
   "originalValue": 1820.00,
   "originalCurrency": "EUR"
 },
 "paymentMethod": "BANK_TRANSFER",
 "paymentRates":[
      {
         "price":{
            "value":588.00,
            "currency":"EUR",
            "originalValue":588.00,
            "originalCurrency":"EUR"
         },
         "dueDate":"2020-12-17"
      },
      {
         "price":{
            "value":1372.00,
            "currency":"EUR",
            "originalValue":1372.00,
            "originalCurrency":"EUR"
         },
         "dueDate":"2021-03-05"
      }
   ],
 "currency": "EUR",
 "language": "de",  
  
 "costs": [
   {
     "serviceId": "111_109918759",
     "label": "CLEANING",
     "costType": "MANDATORY_EXCLUDED_FROM_BASE_PRICE",
     "costUnit": "PER_STAY",
     "pricePerUnit": {
       "value": 100,
       "currency": "EUR",
       "originalValue": 100,
       "originalCurrency": "EUR"
     },
     "totalPrice": {
       "value": 100,
       "currency": "EUR",
       "originalValue": 100,
       "originalCurrency": "EUR"
     },
     "paymentTime": "WITH_BASE_PRICE",
     "maximumCount": 1,
     "conditions": []
   }
 ],
"brand":"HOLIDU"
}

Booking response body

Field	Type	Required	Content
errorCode	Integer	optional	Error code. Required in case of a failed booking.
errorMessage	String	optional	Error message as a String. Required in case of failed booking.
transactionId	String	optional	Transaction/Booking Id generated in your system. Required in case of successful booking.
status	String	true	Status of the booking request. It should be one of eitherCONFIRMED, FAILED
paymentUrl	String	optional	This lets you return an URL to which the user can pay its booking. We will show this URL on the confirmation page, and on the confirmation email.

Example Responses

{
 "transactionId": "123456789",
 "status": "CONFIRMED",
 "paymentUrl" : "https://PAYMENT_LINK.com"
}

{
 "errorCode": XXX,
 "errorMessage": "Please specify the error"
 "status": "FAILED"
}

❗️
Please make sure you send the correct http status in the response. Any response with a response code of 200 will be handled as a confirmed booking independent on any errorCode or errorMessage in the response.

👍
For security measures we recommend you to whitelist our IPs so that we can only do requests to you from the following IPs:

54.77.51.111

34.249.124.33

212.114.208.106

99.80.89.251

34.242.187.158

34.250.93.237