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 GET 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": "fName.lName@email.com",
 "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 object


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 either
CONFIRMED, FAILED

paymentUrlStringoptionalThis 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.


Examples for responses

Booking Response (Successful):

{

 "transactionId": "123456789",

 "status": "CONFIRMED",

 "paymentUrl" : "https://PAYMENT_LINK.com"

}


Booking Response (Failure):

{

 "errorCode": 500,

 "errorMessage": "Some Exception occurred"

 "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

In case you have any questions, please contact providersupport@holidu.com