Skip to main content
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.

ElementNumberTypeDescription
ReservationRQ1Root node.
ReservationRQ/ClientLocator1StringBooking ID in client's system.
ReservationRQ/OnRequest1BooleanIndicates 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/Parameters0..1List of parameters.
Parameters/Parameter1..nParameters for additional information that have been reported in ValuationRS.
@key1StringContains the keyword/Id to identify a parameter.
@value1StringContains the value of the parameter.
ReservationRQ/DeltaPrice0..1Indicates 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.
@amount0..1StringAmount (in the currency returned into the option) that is accepted by the client to be higher than the valuation price.
@percent0..1StringPercentage accepted by the client to be higher than the valuation price.
@applyBoth1BooleanIndicates 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/StartDate1StringStart date to search rates.
ReservationRQ/EndDate1StringEnd date to search rates.
ReservationRQ/MealPlanCode1StringMealPlan code.
ReservationRQ/HotelCode1StringHotel code.
ReservationRQ/Nationality1StringNationality of the Holder (use ISO3166_1_alfa_2 , see MetaData in order to verify if the supplier implements it).
ReservationRQ/Holder1Holder of the booking.
@title1Enum
Titles
Code Description
0 Mr
1 Mrs
2 Miss
3 Ms
@name1StringHolder's name.
@surname1StringHolder's surname.
@email0..1StringHolder's email.
ReservationRQ/Price1Total price of this valuation.
@currency1StringCurrency code (Our system uses a standard ISO - 3 for all suppliers).
@amount1DecimalOption Amount.
@binding1BooleanIf 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.
@commission1Decimal
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.
@minimumSellingPrice1DecimalIndicates 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/ResGuests1List of passengers.
ResGuests/Guests1Passengers.
Guests/Guest1..nDetail of each passenger. If the holder is also a passenger you need to add his/hers information in the gest list.
@roomCandidateId1IntegerRoom candidate Identifier
@paxId1IntegerPassenger id (starting at 1).
Guest/Title1Enum
Titles
Code Description
0 Mr
1 Mrs
2 Miss
3 Ms
Guest/GivenName1StringGuest's given name.
Guest/SurName1StringGuest's last name.
ReservationRQ/PaymentType1String
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/CardInfo0..1Credit card details.
CardInfo/CardCode1String
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/Number1StringCredit card number.
CardInfo/Holder1StringCredit card holder.
CardInfo/ValidityDate1
ValidityDate/Month1StringExpiration month (2 characters).
ValidityDate/Year1StringExpiration year (2 characters).
CardInfo/CVC1StringCredit card security code.
CardInfo/isVCC1BooleanIndicates if the card information provided is from a Virtual Credit Card or not.
CardInfo/VirtualCreditCard0..1Extra information if the card is a virtual credit card.
VirtualCreditCard/VCCActivationDate1StringDate from when the card can be charged. Format: DD/MM/YYYY.
VirtualCreditCard/VCCDeactivationDate1StringDate from when the card will no longer be chargeable. Format: DD/MM/YYYY.
VirtualCreditCard/VCCCurrentBalance1StringThe amount which can be charged to the card.
VirtualCreditCard/VCCCurrencyCode1StringThe ISO currency code of the VCCCurrentBalance.
CardInfo/ThreeDomainSecurity0..13DS data and transaction results.
ThreeDomainSecurity/ThreeDSVersion1StringThree Domain Security version used.
ThreeDomainSecurity/DSTransactionID0..1StringUnique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.
ThreeDomainSecurity/XID0..1StringTransaction identifier resulting from authentication processing.
ThreeDomainSecurity/ECI1StringFor 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/CAVV0..1StringCardholder Authentication Verification Value.
ThreeDomainSecurity/PARes0..1StringPayer Authentication Response.
ThreeDomainSecurity/PAResStatus0..1String
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/PARes0..1StringPayer Authentication Response.
ThreeDomainSecurity/CardEnrolledStatus0..1String
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/SignatureStatus0..1String
Signature Verification Status
Status Value Description
Y Signature of the PARes has been validated successfully.
N PARes could not be validated.
ThreeDomainSecurity/MerchantName0..1StringMerchant name.
ReservationRQ/Rooms1Rooms within this option (room list).
Rooms/Room1..n
@id1StringRoom identifier.
@roomCandidateRefId1IntegerRoom candidate identifier.
@code1StringRoom code.
@description1StringRoom description.
Rooms/Preferences0..1Preference filters at room level.
Preferences/Preference1..nEach filter of preference and its values.
@type1String
Preference types
Preference Type
Smoker
NonSmoker
ExtraBed
Cradle
DoubleBed
TwinBeds
ContigousRoom
Wedding
LateArrival
LateCheckOut
EarlyCheckIn
GroundFloor
TopFloor
WithoutBoucher
ReservationRQ/RoomCandidates1..n
RoomCandidates/RoomCandidate1..n
@id1IntegerId of the requested room (starting at 1).
RoomCandidate/Paxes1..n
Paxes/Pax1..n
@age1IntegerPassenger age on the day of check-in.
@id1IntegerPassenger id (starting at 1).
ReservationRQ/Remarks0..1StringAny customer comments for the supplier to consider (see MetaData in order to verify if the supplier implements it).
ReservationRQ/Preferences0..1Preference filters at the option / general level.
Preferences/Preference1..nEach filter of preference and its values.
@type1String
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​

ElementNumberTypeDescription
ReservationRS1Root node.
ProviderLocator0..1StringBooking 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.
PropertyReservationNumber0..1StringBooking Number in the property´s system (see Metadata method in order to verify if the supplier implements it).
ResStatus1String
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.
Price0..1Total price of this reservation (see MetaData in order to verify if the supplier implements it).
@currency1StringCurrency code (Our system uses a standard ISO - 3 for all suppliers).
@amount1DecimalBook Amount.
@binding1BooleanIf 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.
@commission1Decimal
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.
@minimumSellingPrice1DecimalIndicates 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.
Remarks0..1StringAny remarks about this reservation
BillingSupplierCode0..1StringSupplier'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).
Payable0..1Payable.
@value1Informs 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 TypeError DescriptionComments
101System Exception.Exception not controlled or not classified as general exception.
102Provider Error.Seller returns a particular code/description for an error, which is then transmitted to you in our response.
103Too many requests to the supplier.Your account has surpassed the agreed-upon request limit with the Seller.
104Connection Timeout With Provider.The Seller's response time has exceeded the timeout set in the Buyer's request.
105Communication Error.The connection to the Seller has been refused (we haven't been able to connect to their system).
105Payload 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).
204No 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.).
205Room Candidate Not Supported.The number of room candidates in your request exceeds the maximum set by the Seller.
206Dates Not Supported.Your availability request does not align with the Seller's date specifications.
207Request XML not accepted by Supplier.Your availability request does not align with the Seller's specifications.
301Option 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).
302Hotel not found.Our system is unable to locate the hotel you requested in your Hotels (DescriptiveInfo) method
303Booking 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.