Latest

Blog Detail Title

Short Content Here

by Author Name

Date Published

Developer

IBE Integration Guide

Benjamin Schmid October 10, 2019

Let's talk Internet Booking Engines (IBEs). They work best when directly connected to the PMS, without any intermediaries that might get in the way with delays in room availability, price updates, or other important data that matters for a hotel's offers.

With apaleo, there is no need for intermediaries. apaleo's Core API, especially the Booking API, gives you all you need to implement a powerful IBE. Together with the Java Script based payment widget, powered by our partner and payment processor Adyen, you've got all you need.

Getting offers

In order to get stay offers, call the following endpoint:

GET /booking/v1/offers

{
"offers": [
{
"ratePlan": { "name": "Non Refundable", ... },
"unitGroup": { "name": "Single", ... },
"minGuaranteeType": "Prepayment",
"availableUnits": 22,
"totalGrossAmount": { "amount": 151, "currency": "EUR" },
"cancellationFee": { "code": "STR", "fee": { "amount": 151, "currency": "EUR" }, ... },
"noShowFee": { "code": "NOSHOW", "fee": { "amount": 151, "currency": "EUR" } },
"prePaymentGrossAmount": { "amount": 151, "currency": "EUR" },
"cityTax": { "grossAmount": 21.4, "netAmount": 20, ... },
"timeSlices": [
...
],
"lineItems": [
...
],
"taxDetails": [
...
],
...
},
...
]
}

Once the stay offer has been selected, you can get service offers for the selected rate plan by calling the following endpoint:

GET /booking/v1/service-offers

{
"services": [
{
"service": { "name": "Breakfast", "pricingUnit": "Person", ... },
"count": 1,
"totalAmount": { "grossAmount": 20, "netAmount": 16.81, ... },
"prePaymentGrossAmount": { "amount": 20, "currency": "EUR" },
"dates": [
{
"serviceDate": "2019-10-11",
"amount": { "grossAmount": 20, "netAmount": 16.81, ... },
"isDefaultDate": true
}
]
},
...
]
}

The user should be able to select one or more stay offers and optionally add service offers as extras to his or her reservation.

You can calculate the amount that needs to be pre-paid by summing up the prePaymentGrossAmount for all the selected offers including the service offers.

Getting the money

Using Adyen's Drop-in technology based on Adyen's checkout API, it is really simple to authorize the above calculated pre-payment amount. Hotels can even use the credit card later for merchant-initiated transactions when you are setting the parameters shopperReference, shopperInteraction and recurringProcessingModel as shown in the example below. To ensure apaleo can finalize the transaction correctly, it is important to set all the metadata in the additionalData as well. In order to avoid conflicts, the shopperReference must be a UUID or a GUID.

Please also set the deliveryDate to the earliest arrival of all reservations in the booking so that the payment processor is able to calculate the potential exposure to chargebacks in regards to prepaid reservations properly and can hold back sufficient funds to cover for this risk.

If you want to create a booking with rooms from different properties, then you still can only send in one apaleo property ID. You could take the ID for the property that has the biggest portion of rooms or revenues in the whole booking. The money will be paid out to the bank account of this property then.
{
...,
"configuration": {
"cardHolderName": "REQUIRED"
},
"deliveryDate": "2019-11-17T16:00:00.000+01:00",
"enableOneClick": false,
"enableRecurring": true,
"shopperReference": "575b0100-b261-4a36-94cb-eeb49f7c98d3",
"shopperInteraction": "Ecommerce",
"recurringProcessingModel": "UnscheduledCardOnFile",
"additionalData": {
"metadata.flowType": "CaptureOnly",
"metadata.accountId": "DEMO", // The apaleo account id
"metadata.propertyId": "MUC" // The apaleo property id
}
}

After you've made the payment request to Adyen, you will receive a response which looks similar to this:

{
"additionalData": {
"expiryDate": "9/2022",
"cvcResult": "0 Unknown",
"authCode": "084985",
"avsResult": "0 Unknown",
"cardHolderName": "Expedia VirtualCard",
"cardSummary": "0211",
"paymentMethod": "mc",
"refusalReasonRaw": "00 : Approved or completed successfully",
"acquirerCode": "AdyenMasterCard_13445",
"acquirerReference": "927513404474",
"recurring.recurringDetailReference": "8415689021960227",
"recurringProcessingModel": "UnscheduledCardOnFile",
"recurring.shopperReference": "YOUR_UNIQUE_SHOPPER_ID_IOfW3k9G2PvXFu2j"
},
"pspReference": "851570021506441J",
"resultCode": "Authorised",
"merchantReference": "YOUR_ORDER_NUMBER_Hsz7365uehhgGFFS"
}

Creating the booking

Only then can you create the booking in apaleo using the apaleo Booking API. Use the data from the response to populate the payment account model in the booking request to apaleo:

{
"paymentAccount": {
"accountNumber": "1111",
"accountHolder": "John Doe",
"expiryMonth": "8",
"expiryYear": "2018",
"paymentMethod": "visa",
"payerEmail": "s.hopper@test.com",
"payerReference": "575b0100-b261-4a36-94cb-eeb49f7c98d3",
"transactionReference": "564578124534890J",
"isVirtual": false
},
"booker": { "lastName": "Doe" },
"reservations": [
{
"arrival": "2019-09-18",
"departure": "2019-09-19",
"adults": 1,
"guestComment": "I need a wake up service",
"channelCode": "Direct",
"primaryGuest": { "lastName": "Doe" },
"guaranteeType": "Prepayment",
"travelPurpose": "Business",
"timeSlices": [{ "ratePlanId": "MUC-NONREF-SGL" }],
"services": [
{
"serviceId": "MUC-YOGA",
"dates": [
{
"serviceDate": "2019-09-19",
"amount": { "amount": 20, "currency": "EUR"
}
}
]
}
],
"prePaymentGrossAmount": { "amount": 70, "currency": "EUR" }
},
{
"arrival": "2019-09-18",
"departure": "2019-09-19",
"adults": 1,
"guestComment": "I need a wake up service",
"channelCode": "Direct",
"primaryGuest": { "lastName": "Doe" },
"guaranteeType": "Prepayment",
"travelPurpose": "Business",
"timeSlices": [{ "ratePlanId": "MUC-NONREF-SGL" }],
"prePaymentGrossAmount": { "amount": 30, "currency": "EUR" }
}
]
}

Be sure to set the paymentAccount.payerReference with the shopperReference used to perform the authorization and the paymentAccount.transactionReference with the PSP reference returned from the authorization call.

Also, the prePaymentGrossAmount for each reservation must be set with the sum of the prePaymentGrossAmount of the selected offers.

Nice to have:

If you subscribe to the “reservation created” event using the apaleo Webhooks API, you could implement notifications like: hotel just has been booked, be fast! Pretty cool, right?

Benjamin Schmid

Posted by

Benjamin Schmid
Benjamin Schmid is a co-founder at apaleo. He’s spent more than a decade leading teams to build software that help businesses run smoothly, from ERP systems to SaaS products at SAP hybris. For the last four years, he has taken his product knowledge to the hospitality industry, building up hetras’s API and app platform and now creating apaleo’s open hospitality cloud. When he’s not busy building cool products, Benjamin can be found relaxing in the quietness of the alps or playing sports.
Comments

RECENT ARTICLES

by Andrea Stubbe

06/13/2019

Digital guest journey with apaleo

apaleo is building software for hotels, and our users are people that work at hotels. To create amazing guest experiences we need you, creators of guest facing ...

by Andrea Stubbe

05/02/2019

Push it! Webhooks in apaleo

The notification service allows you to build or set up apps which subscribe to certain events on apaleo (webhooks). When an event is triggered, we send an HTTP ...

WANT MORE AMAZING THINGS?

Subscribe to our a-list for all the fun:

  • Keep up to date with hotel trends
  • Understand what matters most to hotel clients
  • Sweet gifs and special offers

Get it in your inbox every Monday ;)

By entering your email you expressly consent to receive our newsletter every week and other material related to...