4. Booking

The booking request is done after the Booking Info request was completed, and you have collected all the customer details required for the booking.
Booking Request
<request version="4.0">
  <auth>
    <username>example</username>
    <password>example</password>
    <agent>example</agent>
    <clientIp>1.2.3.4</clientIp>
    <clientUserAgent>example user agent</clientUserAgent>
  </auth>
  <hotel-book session="dv.Uw8IU6CsA" clientRef="12345" customerCountryCode="DE">
    <customer>
      <title>Mr.</title>
      <firstName>Test Firstname</firstName>
      <lastName>Test Lastname</lastName>
      <phone type="home">044-772344066</phone>
      <phone type="mobile">044-545966911</phone>
      <email>someone@example.com</email>
      <address>123 main st.</address>
      <postCode>70906</postCode>
      <city>Somewhereville</city>
      <countryCode>DE</countryCode>
    </customer>
    <rooms>
      <room resultId="dv.Uw8JnP3oA">
        <pax-group>
          <pax>
            <title>M</title>
            <firstName>Test Firstname</firstName>
            <lastName>Test Lastname</lastName>
          </pax>
          <pax>
            <title>C</title>
            <age>8</age>
            <firstName>Child Firstname</firstName>
            <lastName>Child Lastname</lastName>
          </pax>
        </pax-group>
      </room>
      <room resultId="dv.Uw8JnP3oA">
        <pax-group>
          <pax>
            <title>F</title>
            <firstName>First Testington</firstName>
            <lastName>Last Testington</lastName>
          </pax>
        </pax-group>
      </room>
    </rooms>
    <special-request-fields>
      <field code="0">this is a very special request</field>
    </special-request-fields>
  </hotel-book>
</request>
Parameter Type Comments
hotel-book @sessionstringthe session id as returned by the search
hotel-book @clientRefstringyour reference
hotel-book @customerCountryCodecountry code2 letter ISO country code of the booking customer
customernode the lead customer details, pretty self explanatory
rooms/room @resultIdstring the room token you wish to book
pax-group/paxnode each person in the room should be specified in a separate pax node. see below notes for details on how to handle children
special-request-fields/field @codeint an ordinal number of your request. you can leave it as 0 if you're sending only 1 node, but sending 2 field nodes with the same code will result in an error. 
special-request-fields/fieldnodethe special request string 
Notes:
  1. the customerCountryCode should be the same country code as was passed to the search
  2. when booking a room with children, the pax node should have an additional age node specifying the child's age. the title can be left empty.
  3. the special-request-fields are absolutely NOT guaranteed. If you will be sending this element it is mandatory to notify your clients that this is only a request and there is no guarantee whatsoever about the fulfillment of this request.
  4. the clientIp and clientUserAgent values are not mandatory, but if you sent them during the search request, you MUST send them here as well, otherwise the rates may vary between the search and booking.
  5. clientRef should be a unique value, as some providers require that, otherwise they fail the booking.
Pay at the hotel booking
In case you are booking a post-pay (pay at the hotel) property, you will need to add the following nodes to your "Customer" node:
<creditCardType>CA</creditCardType>
<creditCardNumber>1234567890123456</creditCardNumber>
<creditCardCVV>123</creditCardCVV>
<creditCardExpirationMonth>12</creditCardExpirationMonth>
<creditCardExpirationYear>2019</creditCardExpirationYear>

Note:
The "creditCardType" must be taken from the "accepted-cards" node in the booking-info response.

Booking Response
<response success="1" session="dv.Uw8IU6CsA">
  <reservation id="dv.Uw9CAbNNQA" status="confirmed" clientReference="12345">
    <item token="dv.Uw8JnP3oA" status="confirmed" id="1">
      <quantity>2</quantity>
      <name>Superior Room, 1 King Bed</name>
      <board code="RO">Room Only</board>
      <remarks>
        You must present a photo ID when checking in. Your credit card is charged at the time you book. Bed type and smoking preferences are not guaranteed.Your reservation is prepaid and is guaranteed for late arrival. The total charge includes all room charges and taxes, as well as fees for access and booking. Any incidental charges such as parking, phone calls, and room service will be handled directly between you and the property.

Fee for in-room wireless Internet: USD 15 (for 24 hours, rates may vary)
Valet parking fee: USD 55 per night
Rollaway bed fee: USD 50 per night
The above list may not be comprehensive. Fees and deposits may not include tax and are subject to change.
      </remarks>
      <source provider="innstant.travel">
        <reference>81028ssn223</reference>
      </source>
      <booking billable="1">
        <price amount="611.16" currency="USD"/>
      </booking>
      <cancellation>
        <frame endTime="2014-02-26 13:35:34" timezone="UTC" type="non-refundable"/>
      </cancellation>
      <pax-groups>
        <pax-group quantityItem="0">
          <pax id="0">
            <title>M</title>
            <firstName>Test Firstname</firstName>
            <lastName>Test Lastname</lastName>
            <age>33</age>
          </pax>
        </pax-group>
        <pax-group quantityItem="1">
            <pax id="0">
              <title>M</title>
              <firstName>Test Firstname</firstName>
              <lastName>Test Lastname a</lastName>
              <age>33</age>
            </pax>
                </pax-group>
      </pax-groups>
    </item>
  </reservation>
</response>
Parameter Type Comments
response @successbooleanwas the request successful - note that this is NOT the booking status response
reservation @idstringthe reservation identifier
reservation @statusstringsee "lookups" for possible returned statuses
reservation @clientReferencestring your reference as received during the booking request
item @tokenstring the room token that was booked
item @statusstring see "lookups" for possible returned statuses
item @idintan incremental counter 
item/quantityint how many rooms were booked under this item 
item/namestring the item name 
item/boardnode the board name as received from the hotel
item/board @codeboard code2 letter normalized board code
item/remarksnode mandatory remarks to show to the customer and on the voucher 
item/source @providerstring the provider from which the booking was acquired 
item/source/referencestring the provider reference 
item/booking @billableboolean is the provider a direct provider (0=direct) 
item/booking/price @amountdoublethe price of the booking payable to the provider
item/booking/price @currencycurrencycurrency ISO code of the price
cancellationnode see cancellation policy section for details 
pax-groups/pax-groupnode booked pax for each room 

On request / Pending bookings
In case the booking status is returned as "on request", it is mandatory to run the Reservation Details Request to verify it's status at least once a day until the status is changed to either confirmed or rejected. if the status does not change after 5 working days, it is mandatory to contact customer support and verify the status manually.

Error during booking
If the booking is not returned as confirmed, you will receive the status attribute as such. In most cases it will be returned as either confirmed or rejected, but some cases will require you to show the booking as Pending, and contact us (or your provider directly in case you're booking from your own provider) for clarification of the actual status.
You will also receive an additional error node to the booking response that will explain what the error is, like so:
<error>
  The rooms booked are no longer available on the hotel's system
</error>
Note that there is a special case that will allow you to "Retry" the booking in case the price changed, and this will be explain in the following section:

Price change during booking (not mandatory)
In some cases the price will change between the search phase and the booking phase. in this case we will not make the booking, but will allow you to offer your client the new booking conditions and ask them to confirm it. 
Note that this step is NOT mandatory, and you can just treat this scenario as a failed booking without further actions required.
<response success="1" session="dv.Uw8IU6CsA">
  <reservation id="dv.Uw9ChGRmMA" status="failed" clientReference="12345">
    <item token="dv.Uw8JnP3oA" status="failed" id="1">
      <error>
        The price changed during the booking attempt, please review the price and send a confirm reservation request to complete it.
      </error>
      <quantity>2</quantity>
      <name>Superior Room, 1 King Bed</name>
      <board code="RO">Room Only</board>
      <remarks>
        You must present a photo ID when checking in. Your credit card is charged at the time you book. Bed type and smoking preferences are not guaranteed.Your reservation is prepaid and is guaranteed for late arrival. The total charge includes all room charges and taxes, as well as fees for access and booking. Any incidental charges such as parking, phone calls, and room service will be handled directly between you and the property.

Fee for in-room wireless Internet: USD 15 (for 24 hours, rates may vary)
Valet parking fee: USD 55 per night
Rollaway bed fee: USD 50 per night
The above list may not be comprehensive. Fees and deposits may not include tax and are subject to change.
      </remarks>
      <source provider="innstant.travel">
        <reference/>
      </source>
      <booking billable="1">
        <price amount="617.002" currency="USD"/>
      </booking>
      <old-price amount="611.16" currency="USD"/>
      <cancellation>
        <frame endTime="2014-02-26 13:35:34" timezone="UTC" type="non-refundable"/>
      </cancellation>
      <pax-groups>
        <pax-group quantityItem="0">
          <pax id="0">
            <title>M</title>
            <firstName>Test Firstname</firstName>
            <lastName>Test Lastname</lastName>
            <age>33</age>
          </pax>
          <pax-group quantityItem="1">
            <pax id="0">
              <title>M</title>
              <firstName>Test Firstname</firstName>
              <lastName>Test Lastname a</lastName>
              <age>33</age>
            </pax>
          </pax-group>
        </pax-group>
      </pax-groups>
    </item>
  </reservation>
</response>
Parameter Type Comments
reservation @statusstringfailed
reservation @idstringthe unconfirmed reservation id
reservation/item/errornodethe reason for the failure
reservation/item/booking/pricenodethe new price of the booking
reservation/item/booking/old-pricenode the previous price of the booking which is no longer valid

In case you wish to confirm the reservation, you will need to send the following request:
Confirm Reservation Request (not mandatory, for use with price change only)
<request version="4.0">
   <auth>
      <username>example</username>
      <password>example</password>
      <agent>example</agent>
   </auth>
   <hotel-confirm-reservation session="dv.Uw8IU6CsA" reservationId="dv.Uw9ChGRmMA"/>
</request>
Parameter Type Comments
hotel-confirm-reservation @sessionstringthe session id used for the booking request
hotel-confirm-reservation @reservationidstringthe unconfirmed reservation id received from the booking price change response
Note: the response will be exactly like the booking response.


Adding the transaction ID

In case you are using slokly for your processing, you can pass the transaction ids in the booking request under the hotel-booking node:
<sloklyTransactionIds>
   <sloklyTransactionId>1234</sloklyTransactionId>
</sloklyTransactionIds>
Parameter Type Comments
sloklyTransactionIds/sloklyTransactionIdnodeThe transaction id you want to connect to the booking
Note: In case you have multiple transactions (like authorize, purchase, 3d, etc.) you can simply add more sloklyTransactionId nodes under sloklyTransactionIds



Comments