Deprecated API

The Legacy Pull Buyers API, our initial Buyers API launched in 2012, is now deprecated and should not be further developed. Instead, we introduced the Hotel-X Buyers API in 2017, which serves as the sole API for new Buyers looking to integrate and participate in our Marketplace.

Reservation

The Reservation operation requests a booking confirmation for a specific list of passengers. It provides the booking locator (booking code), which could be the supplier’s own code or the one sent in request, along with all the charges associated with the booking as well as its status. The returned fields include: ProviderLocator, PropertyReservationNumber, ResStatus, Price etc.

caution

The amount of information returned might vary between Sellers.

Reservation Request

<soapenv:Envelope xmlns:soapenv = "http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns = "http://schemas.xmltravelgate.com/hub/2012/06" xmlns:wsse = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
   <soapenv:Header>
      <wsse:Security>
         <wsse:UsernameToken>
            <wsse:Username>username</wsse:Username>
            <wsse:Password>password</wsse:Password>
         </wsse:UsernameToken>
      </wsse:Security>
   </soapenv:Header>
   <soapenv:Body>
      <ns:Reservation>
         <ns:reservationRQ>
            <ns:timeoutMilliseconds>20000</ns:timeoutMilliseconds>
            <ns:version>1</ns:version>
            <ns:providerRQ>
               <ns:code>suppliercode</ns:code>
               <ns:id>1</ns:id>
               <ns:rqXML>
                  <ReservationRQ>
                      <timeoutMilliseconds>19700</timeoutMilliseconds>
                     <source>
                        <languageCode>en</languageCode>
                     </source>
                     <filterAuditData>
                        <registerTransactions>true</registerTransactions>
                     </filterAuditData>
                     <Configuration>
                        <User>user</User>
                        <Password>password</Password>
                        <UrlAvail>www.supplier.com/avail</UrlAvail>
                        <UrlReservation>www.supplier.com/reservation</UrlReservation>
                        <UrlValuation>www.supplier.com/valuation</UrlValuation>
                        <UrlGeneric>www.supplier.com/generic</UrlGeneric>
                        <Parameters>
                           <Parameter key = "UrlListHotels" value = "http://www.supplier.com/ListHotels"></Parameter>
                           <Parameter key = "Access" value = "22334"></Parameter>
                        </Parameters>
                     </Configuration>
                     <ClientLocator>2537459</ClientLocator>
                     <OnRequest>false</OnRequest>
                     <Parameters>
                        <Parameter key = "extra" value = "31"/>
                     </Parameters>
                     <DeltaPrice amount="10" percent="5" applyBoth="false"/>
                     <StartDate>28/01/2014</StartDate>
                     <EndDate>29/01/2014</EndDate>
                     <MealPlanCode>D</MealPlanCode>
                     <HotelCode>10</HotelCode>
                     <Nationality>ES</Nationality>
                     <Holder title = "Miss" name = "name" surname = "surname" email = "hotelemail@email.com"/>
                     <Price currency = "EUR" amount = "36.20" binding = "false" commission = "-1" minimumSellingPrice="-1"/>
                     <ResGuests> 
                        <Guests>
                           <Guest roomCandidateId = "1" paxId = "1">
                              <Title>Miss</Title>  
                              <GivenName>name</GivenName>
                              <SurName>surname</SurName>
                           </Guest>
                           <Guest roomCandidateId = "1" paxId = "2">
                              <Title>Mr</Title>  
                              <GivenName>name</GivenName>
                              <SurName>surname</SurName>
                           </Guest>
                        </Guests>
                     </ResGuests>
                     <PaymentType>CardCheckInPay</PaymentType>
                     <CardInfo>
                        <CardCode>VI</CardCode>
                        <Number>4321432143214327</Number>
                        <Holder>name surname</Holder>
                        <ValidityDate>   
                           <Month>06</Month>
                           <Year>14</Year>
                        </ValidityDate>
                        <CVC>123</CVC>
                        <isVCC>false</isVCC>
                     </CardInfo>
                     <Rooms>
                        <Room id = "4582" roomCandidateRefId = "1" code = "506" description = "Double Standard.."/>
                        <Preferences>
                           <Preference type = "NonSmoker"/>
                           <Preference type = "ExtraBed"/>
                        </Preferences>
                     </Rooms>
                     <RoomCandidates>
                        <RoomCandidate id = "1">
                           <Paxes>
                              <Pax age = "30" id = "1"/>
                              <Pax age = "30" id = "2"/>
                           </Paxes>
                        </RoomCandidate>
                     </RoomCandidates>
                     <Remarks>I want it a double bed.</Remarks>
                     <Preferences>
                        <Preference type = "LateArrival">14:00</Preference>
                     </Preferences>
                  </ReservationRQ>
               </ns:rqXML>
            </ns:providerRQ>
         </ns:reservationRQ>
      </ns:Reservation>
   </soapenv:Body>
</soapenv:Envelope>

Request Data Breakdown

info

Check the values you need to add in the header and common elements.

Element	Number	Type	Description
ReservationRQ	1		Root node.
ReservationRQ/ClientLocator	1	String	Booking ID in client's system.
ReservationRQ/OnRequest	1	Boolean	Indicates if you want to receive the onrequest options in AvailRS, as long as the supplier returns it in this method (see MetaData in order to verify if the supplier implements it).
ReservationRQ/Parameters	0..1		List of parameters.
Parameters/Parameter	1..n		Parameters for additional information that have been reported in ValuationRS.
@key	1	String	Contains the keyword/Id to identify a parameter.
@value	1	String	Contains the value of the parameter.
ReservationRQ/DeltaPrice	0..1		Indicates price variation permitted by the client (see MetaData in order to verify if the supplier implements it). If the newly entered price doesn't meet the DeltaPrice criteria, an error will occur. In case you omit the DeltaPrice tag, and the integration supports it, we'll consider the price range as 0. Under this condition, the process will proceed as long as the price is the same or lower than the one indicated in the valuation.
@amount	0..1	String	Amount (in the currency returned into the option) that is accepted by the client to be higher than the valuation price.
@percent	0..1	String	Percentage accepted by the client to be higher than the valuation price.
@applyBoth	1	Boolean	Indicates that the range between valuation price and the new price does not exceed the amount and/or porcentage indicated by the client. DeltaPrice Cases applyBoth Description False Indicates that one of the conditions (amount or percentage) has to meet the criteria before reservation. True Indicates that the new price cannot exceed the amount or percentage indicated by the client.
ReservationRQ/StartDate	1	String	Start date to search rates.
ReservationRQ/EndDate	1	String	End date to search rates.
ReservationRQ/MealPlanCode	1	String	MealPlan code.
ReservationRQ/HotelCode	1	String	Hotel code.
ReservationRQ/Nationality	1	String	Nationality of the Holder (use ISO3166_1_alfa_2 , see MetaData in order to verify if the supplier implements it).
ReservationRQ/Holder	1		Holder of the booking.
@title	1	Enum	Titles Code Description 0 Mr 1 Mrs 2 Miss 3 Ms
@name	1	String	Holder's name.
@surname	1	String	Holder's surname.
@email	0..1	String	Holder's email.
ReservationRQ/Price	1		Total price of this valuation.
@currency	1	String	Currency code (Our system uses a standard ISO - 3 for all suppliers).
@amount	1	Decimal	Option Amount.
@binding	1	Boolean	If binding is set as true, then the client can’t sell the product for a lower price that the one set by the supplier. If it set as as false, the client can sell the product for a lower price.
@commission	1	Decimal	Commission Scenarios Commission Description 0 The price returned is net. -1 The supplier has not supplied the sale price nor the commission. This information is in the commercial contract with the supplier. Greater than 0 X = % of the commission applied to the amount.
@minimumSellingPrice	1	Decimal	Indicates the minimum selling price it can be sold (determined by the Seller). If is specified (different than "-1"), that field takes preference to amount. Minimum Selling Price Scenarios Minimum Selling Price Description 0 No minimum selling price is provided. -1 We have no information about MSP from the Seller. Greater than 0 The lowest possible amount that can be sold commercially.
ReservationRQ/ResGuests	1		List of passengers.
ResGuests/Guests	1		Passengers.
Guests/Guest	1..n		Detail of each passenger. If the holder is also a passenger you need to add his/hers information in the gest list.
@roomCandidateId	1	Integer	Room candidate Identifier
@paxId	1	Integer	Passenger id (starting at 1).
Guest/Title	1	Enum	Titles Code Description 0 Mr 1 Mrs 2 Miss 3 Ms
Guest/GivenName	1	String	Guest's given name.
Guest/SurName	1	String	Guest's last name.
ReservationRQ/PaymentType	1	String	Payment Types Code Description MerchantPay The payment is managed by the supplier. LaterPay The payment is managed by the hotel. The customer will use a credit-card as a guarantee for the hotel and the payment will be completed at check in. CardBookingPay The payment is managed by the supplier. The payment is effectuated at the time of booking. CardCheckInPay The payment is managed by the supplier. The payment is effectuated at check in in the hotel.
ReservationRQ/CardInfo	0..1		Credit card details.
CardInfo/CardCode	1	String	Credit Card codes Code Name VI Visa AX American Express BC BC Card CA MasterCard CB Carte Blanche CU China Union Pay DS Discover DC Diners Club T Carta Si R Carte Bleue N Dankort L Delta E Electron JC Japan Credit Bureau TO Maestro S Switch EC Electronic Cash EU EuroCard TP Universal air travel card OP optima ER Air Canada/RnRoute XS access O others
CardInfo/Number	1	String	Credit card number.
CardInfo/Holder	1	String	Credit card holder.
CardInfo/ValidityDate	1
ValidityDate/Month	1	String	Expiration month (2 characters).
ValidityDate/Year	1	String	Expiration year (2 characters).
CardInfo/CVC	1	String	Credit card security code.
CardInfo/isVCC	1	Boolean	Indicates if the card information provided is from a Virtual Credit Card or not.
CardInfo/VirtualCreditCard	0..1		Extra information if the card is a virtual credit card.
VirtualCreditCard/VCCActivationDate	1	String	Date from when the card can be charged. Format: DD/MM/YYYY.
VirtualCreditCard/VCCDeactivationDate	1	String	Date from when the card will no longer be chargeable. Format: DD/MM/YYYY.
VirtualCreditCard/VCCCurrentBalance	1	String	The amount which can be charged to the card.
VirtualCreditCard/VCCCurrencyCode	1	String	The ISO currency code of the VCCCurrentBalance.
CardInfo/ThreeDomainSecurity	0..1		3DS data and transaction results.
ThreeDomainSecurity/ThreeDSVersion	1	String	Three Domain Security version used.
ThreeDomainSecurity/DSTransactionID	0..1	String	Unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.
ThreeDomainSecurity/XID	0..1	String	Transaction identifier resulting from authentication processing.
ThreeDomainSecurity/ECI	1	String	For Visa, American Express, Diners Club and JCB ECI Codes ECI Value Description 05 3DS authentication was successful, transactions are secured by 3DS. 06 Authentication was attempted but was not or could not be completed; possible reasons being either the card or its Issuing Bank has yet to participate in 3DS. 07 3DS authentication is either failed or could not be attempted; possible reasons being both card and Issuing Bank are not secured by 3DS, technical errors, or improper configuration. For MasterCard ECI Codes ECI Value Description 00 3DS authentication is either failed or could not be attempted; possible reasons being both card and Issuing Bank are not secured by 3DS, technical errors, or improper configuration. 01 3DS authentication was attempted but was not or could not be completed; possible reasons being either the card or its Issuing Bank has yet to participate in 3DS, or cardholder ran out of time to authorize. 02 3DS authentication is successful.
ThreeDomainSecurity/CAVV	0..1	String	Cardholder Authentication Verification Value.
ThreeDomainSecurity/PARes	0..1	String	Payer Authentication Response.
ThreeDomainSecurity/PAResStatus	0..1	String	Payer Authentication Response status Status Code Description Y Successful Authentication. N Failed Authentication. U Unable to complete Authentication. A Successful Attempts Transaction. B You can proceed to authorisation using the information received. R Authentication Rejected.
ThreeDomainSecurity/PARes	0..1	String	Payer Authentication Response.
ThreeDomainSecurity/CardEnrolledStatus	0..1	String	Card Enrollment Status Status Value Description Y Cardholder is enrolled. Bank is participating in 3-D Secure protocol and will return the ACSUrl. N Cardholder Not Participating – Cardholder is not enrolled. U Unavailable. The DS or ACS is not available for authentication at the time of the request.
ThreeDomainSecurity/SignatureStatus	0..1	String	Signature Verification Status Status Value Description Y Signature of the PARes has been validated successfully. N PARes could not be validated.
ThreeDomainSecurity/MerchantName	0..1	String	Merchant name.
ReservationRQ/Rooms	1		Rooms within this option (room list).
Rooms/Room	1..n
@id	1	String	Room identifier.
@roomCandidateRefId	1	Integer	Room candidate identifier.
@code	1	String	Room code.
@description	1	String	Room description.
Rooms/Preferences	0..1		Preference filters at room level.
Preferences/Preference	1..n		Each filter of preference and its values.
@type	1	String	Preference types Preference Type Smoker NonSmoker ExtraBed Cradle DoubleBed TwinBeds ContigousRoom Wedding LateArrival LateCheckOut EarlyCheckIn GroundFloor TopFloor WithoutBoucher
ReservationRQ/RoomCandidates	1..n
RoomCandidates/RoomCandidate	1..n
@id	1	Integer	Id of the requested room (starting at 1).
RoomCandidate/Paxes	1..n
Paxes/Pax	1..n
@age	1	Integer	Passenger age on the day of check-in.
@id	1	Integer	Passenger id (starting at 1).
ReservationRQ/Remarks	0..1	String	Any customer comments for the supplier to consider (see MetaData in order to verify if the supplier implements it).
ReservationRQ/Preferences	0..1		Preference filters at the option / general level.
Preferences/Preference	1..n		Each filter of preference and its values.
@type	1	String	Preference types Preference Type Smoker NonSmoker ExtraBed Cradle DoubleBed TwinBeds ContigousRoom Wedding LateArrival LateCheckOut EarlyCheckIn GroundFloor TopFloor WithoutBoucher

Reservation Response

After each request, the Seller will process the data and provide you with a response. Upon receiving a Reservation request, the Seller will send you a corresponding Reservation response.

The response options include either success or an error. If successful, it will indicate that the reservation has been completed successfully.

caution

Be aware that you can receive an error and a reservation status OK in the same response, in this case the booking is confirmed. You should always consider the reservation status returned.

Success

<ReservationRS>
   <ProviderLocator>102</ProviderLocator>
   <PropertyReservationNumber>HCN8273</PropertyReservationNumber>
   <ResStatus>OK</ResStatus>
   <Price currency = "EUR" amount = "36.20" binding = "false" commission = "-1" minimumSellingPrice="-1"/>
</ReservationRS>

Success Response Data Breakdown

Element	Number	Type	Description
ReservationRS	1		Root node.
ProviderLocator	0..1	String	Booking ID in the Supplier´s system. It will always be returned if the ResStatus is OK or RQ. It could not be returned when the ResStatus is CN or UN, depending if the supplier returns it.
PropertyReservationNumber	0..1	String	Booking Number in the property´s system (see Metadata method in order to verify if the supplier implements it).
ResStatus	1	String	Reservation Status Status Code Description OK The reservation was completed with no problems. RQ The reservation was completed but the product is still not available, so the reservation goes into a waiting list (Request). CN The reservation was completed but due to a supplier error or a timeout the system will immediately cancel the reservation to prevent further possible errors. UN The reservation was completed but due to a supplier error or a timeout, the reservation status is unknown. It is the client’s responsibility to check if the booking is OK.
Price	0..1		Total price of this reservation (see MetaData in order to verify if the supplier implements it).
@currency	1	String	Currency code (Our system uses a standard ISO - 3 for all suppliers).
@amount	1	Decimal	Book Amount.
@binding	1	Boolean	If binding is set as true, then the client can’t sell the product for a lower price that the one set by the supplier. If it set as as false, the client can sell the product for a lower price.
@commission	1	Decimal	Commission Scenarios Commission Description 0 The price returned is net. -1 The supplier has not supplied the sale price nor the commission. This information is in the commercial contract with the supplier. Greater than 0 X = % of the commission applied to the amount.
@minimumSellingPrice	1	Decimal	Indicates the minimum selling price it can be sold (determined by the Seller). If is specified (different than "-1"), that field takes preference to amount. Minimum Selling Price Scenarios Minimum Selling Price Description 0 No minimum selling price is provided. -1 We have no information about MSP from the Seller. Greater than 0 The lowest possible amount that can be sold commercially.
Remarks	0..1	String	Any remarks about this reservation
BillingSupplierCode	0..1	String	Supplier's billing code. Will be returned if the supplier has different billing accounts and this is informed in the reservation (see MetaData in order to verify if the supplier implements it).
Payable	0..1		Payable.
@value	1		Informs Payable.

Error

<ReservationRS>
   <operationImplemented>true</operationImplemented>
   <applicationError>
      <code/>
      <type>204</type>
      <description>Supplier returns 0 results in availability.</description>
      <httpStatusCode>0</httpStatusCode>
   </applicationError>
</ReservationRS>

Error types that will be included in the response in the event of an error

Error Type	Error Description	Comments
101	System Exception.	Exception not controlled or not classified as general exception.
102	Provider Error.	Seller returns a particular code/description for an error, which is then transmitted to you in our response.
103	Too many requests to the supplier.	Your account has surpassed the agreed-upon request limit with the Seller.
104	Connection Timeout With Provider.	The Seller's response time has exceeded the timeout set in the Buyer's request.
105	Communication Error.	The connection to the Seller has been refused (we haven't been able to connect to their system).
105	Payload too high.	The size of the response by the Seller surpasses the size limitation established on our side for optimal performance (20000 options or 15MB).
204	No results found.	Seller does not return any results for the specific availability criteria set in the Buyer's request (e.g. hotel, dates, market, etc.).
205	Room Candidate Not Supported.	The number of room candidates in your request exceeds the maximum set by the Seller.
206	Dates Not Supported.	Your availability request does not align with the Seller's date specifications.
207	Request XML not accepted by Supplier.	Your availability request does not align with the Seller's specifications.
301	Option Not Found In Valuation.	Seller fails to return the option previously chosen by the Buyer in Search response (the option is no longer available). This error can be encountered in Quote response and Book response (whenever the integration requires an additional Quote to the Seller).
302	Hotel not found.	Our system is unable to locate the hotel you requested in your Hotels (DescriptiveInfo) method
303	Booking not confirmed.	Seller hasn't been able to confirm a booking for some reason (is not very common and might be returned in reservation response).

Frequently Asked Questions

In what cases might there be a price difference between Reservation and Valuation methods?

We cannot guarantee that the price will be returned in Reservation, given that this is something which depends on the supplier, and unless they provide us the price in their response, there is no way for us to return it to you.

If the price returned in Reservation method is different than the one returned in the Valuation method, 4 cases could occur. Below, we have explained each of these cases and what should be done if either of them occur:

Case 1

The price in Reservation is lower than the price in Valuation. The selling price for the final customer will be the one in valuation, as this is the one that will be accepted by them at the time of booking.

Case 2

The price in Reservation is higher than the price in valuation:

Case 2.1

The supplier allows DeltaPrice and you allow a price change of, for example, up to €10, indicating it in through our DeltaPrice field (explained in the previous section):

Valuation:

<Price currency = "EUR" amount = "110" binding = "false" commission = "0"/>

Reservation:

<Price currency = "EUR" amount = "110" binding = "false" commission = "0"/>

When making reservation, you must pay the supplier €110, given that you have decided not to lose the booking even though the price has increased with €10 compared to Valuation.

Case 2.2

The supplier allows DeltaPrice and you DO NOT allow price change. In this case we will return an error, as you do not permit a higher reservation price than the one already established in Valuation.

Case 2.3

The supplier DOES NOT allow DeltaPrice. If the supplier returns a higher price in Reservation than he does in Valuation, then the difference should be reported, as you have not specified in any way that the price can be changed. In this case the supplier has to cover the price change.