All you need to know

In case a customer chooses to book one of your apartments on Holidu, Holidu will send a booking notification to your defined endpoint.

The booking notification is a JSON objects in POST request which contains multiple information like booking arrival/departure dates, guest receipt, payment processing, etc..., so all data that you provided through the API to Holidu and which is relevant for you to process the booking.

To ensure a good user experience, there are certain requirements.

• The timeout for the whole booking flow is 30s. Every booking that takes longer than this time will be considered as declined and shown as such also to the customer.
• Every successful booking needs to contain a transactionId to identify the booking in your system, responses without transactionIds are considered as declined.
• Declined bookings need to have a clear reason why it was declined. The ratio of declined bookings should stay always below 1%.
• Depending on your payment integration, you have to include a payment link in every successful booking response. With this link, customers should be directed to a page where they can immediately pay for their booking.

Successful booking

{
 "transactionId": "987654321",
 "status": "CONFIRMED",
 "paymentUrl" : "https://PAYMENT_LINK.com" //OPTIONAL, ONLY CERTAIN CASES
}

Unsuccessful Bookings:

A booking might fail due to various reasons, like apartment unavailability, difference in price from what you expect, or a payment issue. The response should have the correct HTTP Status and include in the body an error message, error description, and the status FAILED.

{ 
 "errorMessage": "Please use one of the error messages from Holidu",
 "errorDescription": "Please describe the error details",
 "status": "FAILED" 
}

For more descriptive error handling, please follow the below guidelines:

• In case of price mismatch, kindly include the expected price in the errorDescription.
• For payment issues, you can always send us the error message you are receiving from different entities.
• All reasons not stated above will be treated as an API outage from your end and we may deactivate your connection until further checks.
• Please make sure to keep the response time ideally under 2s in order to prevent timeouts.

Requirements for guests communication:

After a successful booking, It's mandatory to send an email to the guest within two hours which includes all the booking info, payment schedule, and any further notes.

Depending on the payment integration you have with Holidu, you may need to send out further payment instructions. In any case, you are fully responsible for the check-in communication.

❗

Caution

• Our partners should always have an acceptable error rate and we will always work on enahncing the success rate with you.

• For security meseaures, kindly make sure to whitelist all our IPs to avoid any server errors, in case you are using our PCI payment method, kindly check this link here for our PCI partner IPs.

  List of our 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 want to use Basic Access Authentication instead of IPs Whitelisting, kindly refer to your technical account manager and you will be guided throughout the whole process.

👍

Versioning & Adabtability:

ALWAYS try to build your system independent on the order of the fields. Holidu may change the order at any point in time without any notification.

Be agnostic for unknown fields, so we always improve the booking notification request by adding additional data at any point without any prior notification.