It is up to the XML to enforce collecting the CVV2 at the UI level, as BookingCenter's use of 'require CVV2' can not be enforced when an XML developer is developing the UI for the booking process.

If you are developing an XML solution for an Owner(s) of Unit(s) part of an Owner Channel Program (https://www.bookingcenter.com/nontraditional/), then the ability to make changes to the 'Auto Assign Room' is not within your command - that setting affects all bookings within the PMS and thus is the choice of the owner of the PMS.  BookingCenter won't be able to assist when attempting to Save a Booking and receiving this message, as the message displays that a specififc room is not available for all days the booking is attempting to be saved.  In such error conditions, the XML developer should provide error reporting to their Unit Owner(s) to make sure the booking is saved manually via the PMS, Owners Area, or Agents Area.

• Availability and booking interface between BookingCenter's system and a customer's website application presented as a web service using SOAP.
• SOAP messages using the OTA schemas based on the OTA 2008B Specification from http://www.opentravel.org/  with online documentation is available at http://opentravelmodel.net/pubs/specifications/Specifications.html.

Platform support

• Our SOAP WSDLs are compatible with Microsoft's .NET platform and NuSOAP (the PHP variant for SOAP). Options exist for other development platforms, but we support these.
• No restrictions on server implementation, as it has no impact on client.
• SSL security certificate needs to be mainatined by the XML developer, as the 'host' website where shopping and transactions occur is the website serving the web pages and not BookingCenter's secure server. The communication between the XML developer and BookingCenter, however, does take place over secure SSL communication.

Service Definition

• The XML Service supports multiple search criteria such as availability, rates, rooms, packages, amenities, activities, etc.
• Availability is data is taken from data coming from any Desktop Pro, MyPMS, or Management Tool customers.

References

• http://www.opentravel.org/
• http://ws.apache.org/axis/
• http://ws.apache.org/wss4j/
• Our KnowledgeBase area for XML developers: https://support.bookingcenter.com/index.php?/Knowledgebase/List/Index/8/xml-team

Support

We have a series of knowledgeBase articles at: https://support.bookingcenter.com/index.php?/Knowledgebase/List/Index/8/xml-team that can help you get going and 'scope' out the development of an XML web services project using BookingCenter.  BookingCenter will only provide general support for a webmaster/developer who attempts the XML web service for a customer. But BookingCenter can be hired to develop a custom 'Booking Engine' or other application. Just contact us at: http://www.bookingcenter.com/contact to request a quote after you send us a 'wire frame' and/or diagram of your intended screens and detailed functionality.  We need a detailed description of what you want prior to quoting a price or time estimate.

In order to examine the BookingCenter API documents, you will need to download the NDA (non disclosure, available at: http://files.bookingcenter.com/API_use_NDA.pdf, sign it and email it to info@bookingcenter.com or fax it to us at +1-718-228-5959 (please append a note telling us which BookingCenter customer you are working with). We will then send the appropriate documentation, login and info for you to test your code against our 'Test System' (if your customer is there), and then release to our production systems once readied. 

1. 'auto-pilot' meaning the external system would make changes no more than every 6 hour to 24 hours (2-3 times day).
2. manually - meaning the customer can change rates when needed.  These changes can therefore occur quite often, but BookingCenter will enforce a reasonable minimum threshold to avoid dragging down our API interfaces.  

When implementing the messages for Rate Updates, it is expected that consideration will be made to deploy the least number of XML messages to accomplish the business goals.  For example, a single message for each rate ID to be altered should be incremental and affect only changes to the rate needed for the specified time period needing changing.  Thus, only 'delta differences' - and not a blanket message to alter a rate for a year, for example - should be messaged.  Implementing smart coding from the developer will assure that BookingCenter can support the developer with use of the XML service ongoing.

It is also expected that any developer wishing to use an interface will first read the basic understanding of the XML Web Services from BookingCenter (posted here); then sign and return the NDA provided at that URL in order to gain credentials to a test system; and understand that BookingCenter will enforce a reasonable message threshold from any partner who abuses the update process to avoid dragging down our interfaces with other system (OTAs, GDS, PMS systems, etc).  If BookingCenter notices that a partner's implementation of the web service is causing harm, BookingCenter reseves the right to stop access at any time from a partner to avoid disrupting BookingCenter's APIs or that of our customers.  We will, however, attempt to work with any partner who is shut off from the web service to make sure proper feedback is provided to make the interface work efficiently for all parties. 

Implementation Help

• Make sure that each XML mesages carries with it proper authentication (what we call the Site ID and password) when posting rate mesages.  BookingCenter can not provide this ID to a developer, it must be provided by the property customer (the 'Site'). This is not the User account that a front desk or manager uses to login to MyPMS, for example, but the authentication for the Site.  Note that if the authentication were to change, then the Site would need to inform the developer, else authentication failures would entail.
  
  
• The developer would want to test to see their rates being stored properly. To do this, the customer would have to allow the developer to use a login and view the 'Setup | Rates | Rate Grid' area of MyPMS or the Members Area for access to view rate updates in 'real time'.  The developer can use the Site ID and password to access https://members.bookingcenter.com or https://members-test.bookingcenter.com (depending on whether checking test or production) to view rates and check for authentication status.  If the ID and password used can't auth https://members.bookingcenter.com, then it can't auth the messages.
  
  
• Tax Calculation Error (<Error Type="6" ShortText="Error: Tax Calculation Error"  Code="0" />)
  This a common issue when a property has a TAX VALUE and the developer didn't notice the 2 needed values - taxed and non-taxed.  Let's say, for example, that a sample property has a tax rate of 12.5%.  There are 2 values that need to be sent: AmountBeforeTax and AmountAfterTax.  In the example here, it would need to be reflecting this in your message as AmountBeforeTax="200.00" AmountAfterTax="225.00".  
  
  Note that this same logic is needed for tax-inclusive rates (such as VAT or GST rates) as well as tax-exclusive rates (such as seen in the USA).  You can get the tax policies for a particular Site from the OTA_HotelDescriptiveContentNotifRQ/RS messages Occupancy Tax section.
  
  
• Reduce Messages. Each XML message can contain multiple rates by repeating the <Rate PLan> section of the message with as many Rates as are needed to change.
  
  
• Use Dates Wisely.  Send the longest date range possible in the XML message in order to reduce the number of messages. If the rate does not need to change for a date(s) then it's best not to send a message at all.
  
  
• Closed to Arrivals.  BookingCenter supports Closed to Arrival for a single day or a comma separated string in the StayOverDate.  Thus, StayOverDate="Thu" will work to make the Thurs a 'closed date' as well as StayOverDate="Thu,Sat" will work.
  
  
• Opening and closing Rate Plans. If there is no StayOverDate specified in the message, then the days are opened up by default.  This is how a prior closed date for a rate could be 'opened up' again. But beware of a message that sets the CTA indicator, but then another series of messages with no StayOverDate - this will reset the CTA indicator.  Always send the StayOverDate unless you want the days to all be opened.

Use a File system 

We suggest caching static copies of non volatile messages (which all messags in this API message are) locally. All you need then is a routine to call the message and save the response to a file, which can then be loaded when needed and refreshed when needed.  This will make your Booking Engine faster for sure.

Images

<MultimediaObjects> <MultimediaObject> 
<Image>Room SUITE</Image> <URL>https://images.bookingcenter.com/ROGERS/images/ROGERS_SUITE.jpg</URL> 
</MultimediaObject> </MultimediaObjects>

Thus, an image for the Room Type: SUITE can be retrieved by the URL above where <ROGERS> is the Site ID with an images directory, and the file name and URL to the Room type Suite is ROGERS_SUITE (always using all CAPS).

Inventory Items

The Inventory Item message, by default, returns ALL items in the Property Setup area. Thus, without requesting only those set as 'Sell Online' there would be no way to differentiate which ones ought to be considered 'online sales' (ie to display on the Booking Engine). If the developer sends "online" in their Items message request instead of "yes", they will have online only items returned.  Thus, a developer can use this flag to segregate the 'online' from 'offline' Items setup by the PMS, if desired.

Packages

When one queries for Rate and Availaility, the array sent back has a Rate Type indicator that allows a developer to sort those rates that are Packages from those that are not. The Package indicator will show the price (based on dates and Adults/Children etc queried); whether the Package is FIXED or DYNAMIC; the optional <yes/no> of Items included in that particular Package; and the Quantity and Extended Cost of the Items included and/or optional.  With this information, a developer can be decisive about what Package to save (via the SaveBooking message), with which Items, and determine the Qty and Cost of the Items to save with the Booking.  This is the way to display and save Packages that are setup by the property.

If a developer wished to ignore the PMS' setup of Packages, and instead save Items with Rates as the developer wishes, this can be done. However, note that this might fall outside of what the property desires, so get permission before making these merchandising decisions.  To do this, the developer would query the Items (via the XML call); know which ones are available for sale (online vs. offline, for example); and then save the Items with the Room(s) and Rate(s) booked to be whatever the developer chooses.  The Items must have existing Item Codes (determined via the Items query), but in this way the developer is making Packages 'on the fly' and posting Items with the Booking.

The following are the specific Restriction Messages.  Use this for reference when deciding how you want to display restriction messages in the XML client app:

PROMO CODE HAS NO ALLOCATIONS >>> Sorry, no more rooms are available to this agent/special for these dates.

NO AVAILABILITY FOR ANY TYPES >>> Sorry, no rooms are available between Thu 22-Mar-2018 and Sun 25-Mar-2018 suitable for 1 Guests.

MAX GUESTS EXCEEDED FOR ALL TYPES >>> Sorry, no rooms are available between Wed 14-Mar-2018 and Thu 15-Mar-2018 suitable for 10 Guests.

IF A TYPE HAS NON CONTIGUOUS ROOMS >>> ATTIC Rack Rates unavailable

RESTRICTIONS:

CLOSED >>> we are still showing the results screen but next to the Rate description it says "unavailable" and Rate Plans says "Closed"

CLOSED TO ARRIVALS >>> we are still showing the results screen but next to the Rate description it says "unavailable" and Rate Plans says "Closed to arrival on Wed 14-Mar-2018"

MIN LOS >>> we are still showing the results screen but next to the Rate description it says "unavailable" and Rate Plans says "Minimum Stay is 3 Nights"

MAX LOS >>> we are still showing the results screen but next to the Rate description it says "unavailable" and Rate Plans says "Maximum Stay is 3 Nights"

If a Site is using MyCard (TSYS, Vital, Visanet, or Authorizenet) as payment gateway, and the Site is set to take 'Online Deposits' (ie, some money is needed before confirming a booking) and a specific Booking cannot authorize the amount required by the Deposit, then the developer needs to know what can happen.

The basic response codes from a credit card attempted authorization will show the Booking ID that has been 'saved' in INCOMPLETE status and the message "Failute to obtain authorization".

Note that the booking is now holding inventory, as it's a real booking with a Booking ID.  But it's going to stay in Status= INCOMPLETE for 15 minutes to give the XML developer time to provide a valid card in order to obtain the authorization for the deposit amount.  If the 15 minutes passes and there is no authorization posted to the booking, the booking will be cancelled and the inventory 'freed up'. The Room could then be-rebooked.

The method to update the Booking in Status= INCOMPLETE is to send the 'Update Authorization' message and get a verification that the authorization is now saved.  The booking then gets updated to become Status=CONFIRMED and the deposit amount is posted against the Booking in BookingCenter.

If the XML developer does not update the booking as described above, the booking information will be saved but as a CANCELLED booking.

BookingCenter has a system for managing access to customer's XML data - what we call credentials, with details found in this article - for both reading and writing data.  Because our customer is the PMS user, and not the 'Owner' of a specific Unit, the credentials provided to a developer must be provided by the PMS owner.  BookingCenter is not liable for sharing these credentials, which could have un-intended consequences for the PMS owner.  The PMS owner needs to know that sharing these credentials offers the developer access to data in their PMS and the ability to alter that data.  Proceed with caution.

When saving a Booking to an Owner's Unit Type, there are considerations that must be planned for:

1. Will the system automatically save a Booking to a specific Unit, or just to a Unit allocated to a Type?  See this article for details on this topic.
2. How will the developer choose which Type from an Agent query to save the booking against?  The answer to this question is based on the business goals leading the developer to make the XML solution in the first place.  But consider that trying to Save a Booking without first querying availability could result in a "No Rooms Available" Message when attempting the save procedure.  See this article for a discussion on this topic.
3. Will the Owner and/or Agent login to view their bookings via the Owners Area or Agents Area?  If so, the booking must be set correctly with the Owner and/or Agent login IDs to view their booking(s) in these areas.  When setting the Agent ID, the developer must use the correct Agent ID and it is not the one that the Agent uses to login to the Agents Area.  Rather, it is the Agent as entered in the PMS.  
   
   As an example, if the Agent is 'DEMO' and the Site is 'BCDEMO' then this agent would login to the Agents Area as BCDEMODEMO.  But the developer of the XML needs to use the correct terms for the OTA XML code, which in this example is as follows:
   
   <BasicPropertyInfo AgentCode="DEMO" HotelCode="BCDEMO" ChainCode="BC"/>.
4. Can an Owner and/or Agent make bookings via the Owners Area or Agents Area while the XML service and/or the Channel Manger is also making bookings, thus bookings are entered via multiple sources?  The answer here is YES.  If an Owner and/or Agent were to make a booking via the Members/Owners/Agents Area, that booking will save and occupy availability.  If one were to attempt to insert a booking via the XML service, for same dates and times, an ERROR will return that there is no availability.  So, the two methods (manually via the Members/Agents/Owners Area and also via the XML service/Channel Manager) can be used concurrently, but there can only be one that makes a booking for a specific unit for the specific date.  
   
   It is our recommendation that an XML developer always first query availability before attempting to save a new booking to avoid a "No Rooms Available" Message when attempting the save procedure.
   
   

5. Assuming the PMS ownership provides agreement to the Owner for using the APIs (we provide on our API documentation pages), the two messages the developer(s) will need to develop, at minimum, are:

   1) Connect to the PMS to save a new booking that occurred in an outside system using the OTA_HotelRes (ie, 'new booking’) message.

   2) If a modification occurs to an existing booking in the outside system, or a cancellation occurs to an existing booking in the outside system, then use the OTA_HotelResCancel (Cancel a booking) to cancel the existing one that was placed into BookingCenter prior.  If only a cancellation event, this is all the the developer is required to do. If the goal was to insert a ‘modified’ booking to one placed into BookingCenter prior, then the developer will then save the modified booking information as a 'new booking’ and place the ‘CRS_Confirmation number’ from the outside system with this new booking.

   The BookingCenter will always return a OTA_HotelRes (ie, 'new booking’) message with a BookingCenter-generated Confirmation Number and always return a cancellation number from an OTA_HotelResCancel (Cancel a booking) message. It is best practices that these reference numbers are stored in a mapping file the developer manages to record the booking RefNumbers returned by BookingCenter (the ‘confirmation number’ and/or ‘cancellation number') in order to use that for cancelling later (if needed).  In addition, it is recommended that the outside system RefNumber saved when the booking was originally saved is placed into the BookingCenter booking as the ‘CRS_Confirmation number’ so that the ‘confirmation number’ of the outside system is linked with the ‘confirmation number’ stored in BookingCenter.  

BookingCenter does not support an XML developer in these situations who is not part of an Owner Channel Program.  If an XML developer is not sure how to achieve their desired results, BookingCenter provides hourly rate consultation to achieve these goals.  Contact the Sales Department (sales@bookingcenter.com or +1-707-874-3922 ext 201) if you need assistance in developing an XML solution for an Owner(s) of Unit(s).

• Cancellation Number: (you can define your own number or let the system auto-generate one)
• Cancellation Fee: (you can set a fee, thought this has no bearing on any PMS product.
• Message: You can save a message about the cabncellation, such as: "guest cancelled by phone call".
• Phone: You can place a phoine number to call someone back or refer to the person recording teh cancellation.
• Cancelled By: Insert a valid PMS user name to record who did the cancellation.  If you have no idea whu to place here, use 'xml' so it's clear.

If a developer wished to MODIFY an existing booking, then they have two choices:

1. Either send the Rate and Availaility query to find out rate and avail for the new desired dates, and then cancel the existing booking make a New Booking.  This assures they get the rates desired for the modification, but doesn't guarantee accurate availability, based on the cancellation they are about to perform.  It could be a false positive.  
   
   For example, if there was no availabiity for a date range because the existing booking is still blocking the availability, the developer could receive a false positive that the modification wasn't possible due to no availability.
   
   
2. Or the developer could  and then send the Rate and Availaility query to find out rate and avail for the new desired dates, and make a New Booking.  This assures they get the accurate availability, based on the cancellation, but they won't know the actual rates for the modification until after they cancelled the booking. 
   
   Thus they could have cancelled a booking they wanted to save because it was priced better.  There is no perfect solution to this dilema, so choose your preferred option, but there is no solution for a direct 'modification' message.

However, since most developers would use Inventory Items already set in the PMS (with proper description, cost, etc) this should not be a limitation.  See this article for details on Items that a property has decided are 'Live' and which are set 'Not Live' to sell online.

However, where a developer would prefer to build Packages and Items 'on the fly', we recommend using MyGuest.  With this product, you can place as many 'Guest requests' as needed, and with whatever notes describing the Item(s) desired.  Because each MyGuest Request is saved with the Booking ID, these Requests are linked from the Booking, and in front of staff on the Front Desk, these 'Requests' make ideal places for getting creative with extended info about Item(s) placed onto a Folio.

If you look at the MyGuest Pubic API, it shows a Notes:  element that would be used.  Anything you place here is free form text, thus flexible and availale for staff for tracking and reporting purposes.  In addition, you can use the Request ID to 'consume via the API' tho constantly update the Request with additional details as the Item is sold, altered, deleted, and ultimately delivered to a Guest.  

{
  "hotel_id": 2,
  "room": "32",
  "booking_id": "1332025-4X",
  "guest": {
    "email": "joeb@banks.com",
    "name": "Joe Banks",
    "phone": "7075551414"
  },
  "guest_notify": false,
  "form_category": "Treatment",
  "form_name": "Spa Menu",
  "form_fields": {
    "Notes": "We'd like hot towels and a room to meditate in, which will need to be large as we bring our dogs and cats on meditation retreats with us. ",
    "swedish1": 2,
    "pregnancy2": 1
  }
}

1) Connect to the ‘PMS/CRS’ and retrieve hotel rates and availability, with specifics for finding which rates are Packages, what Items they include, and Quantity and Price.  To learn about rates and availabiity for an XML developer, we recommend reviewing the KnowledgeBase articles here.

OTA_ HotelAvailRQ/RS-

As summarized at: https://docs.bookingcenter.com/display/MYPMS/APIs+and+Web+Services+Available+From+BookingCenter this message provides an array with Type and Rate availability, and you could parse the array to get the ‘lowest’ available rate, or whatever hierarchy desired to offer a Guest. The credentials (User ID and password or API key) enable this API call to return what is needed when formatting this message for showing by date or Type.  

2) Save the Booking, what we call the NewBooking message

OTA_HotelRes

This is the message that sends a 'payload' of all data needed to save a booking.  As we explain at: https://support.bookingcenter.com/index.php?/Knowledgebase/Article/View/667 when querying and selling Packages, understanding the way your API calls for Inventory Items (which constitute the ‘parts’ of a package), and then saving them with a booking, is critical. 

If the BookingCenter customer is using a Payment Gateway, then you can request the server 'process' the deposit amount (payment) as part of saving the Booking.  The deposit policy for the specific Rate & Availability will be sent with the OTA_ HotelAvail so doesn't have to be cal;culated by teh developer.  If a deposit/payment is requested by the developer, if we get an authorization, then the server sends back the Booking ID (reference number) and you can be assured the 'payment' was saved with the Booking. The payment will be qued for the next merchnat account 'Batch' and assocaited to the booking.  See: Point of Sale/MyCard (credit cards, hardware, etc.) part of the XML KnowledgeBase to understand the settings for requesting a payment or saving an 'offline' payment a developer may make, and to understand errors with failed deposits/payments.

The WSDL allows one to use both Time and Dates to query for bookings that match common requests. Below helps identify what the results provide:

ResStatus="Reserved" = confirmed 
ResStatus="Requested" = unconfirmed 
ResStatus="Cancelled" = Cancelled 
ResStatus="Active" = checked in 
ResStatus="Complete" = Complete 

The date type has an option "All" and "Cancelled", as well.

Date Type "All" "LastUpdateDate" "MadeOnDate" "ArriveDate" "DepartDate" "CancelledDate" are self-explanatory.