home > support > API > Marketplace API > API: booking creation
Creating bookings via XML API
About this page
This page details the subset of the TourCMS Marketplace API related to booking creation only. Don't forget there are also booking searching, retrieval and modification API methods (in addition to all of the other areas the API covers).
A very rough implementation of the methods outlined on this page has been released as the Very Basic Booking Engine.
Alternatives
Hosted Booking Engine
The traditional method for creating bookings in TourCMS is to use the standard hosted Booking Engine pages, these can be added to any web page just as a regular web link (URL) and so are technically much simpler to implement than the API. Of course staff can also make bookings by logging in to TourCMS and heading to "Bookings".
Enquiries
Enquiries can be seen as an alternative to bookings rather than as an alternative to the API. Enquiries are general purpose (i.e. not necessarily product / date specific) free text entries that can be lodged against a customer record (new or existing) inside TourCMS.
Tour Operators can add enquiry forms to their website, Marketplace Partners can use the create enquiry API.
Booking creation API methods
Mandatory steps
This list is presented in the chronological order you would likely follow when creating a booking engine or programatically entering a booking into TourCMS. These don't necessarily have to be presented to the customer as separate steps/pages.
Show Tour
Not strictly a booking API call as this is also the call you will likely be using if you display the full product details to the customer. This call returns vital information for those building their own booking engines as it details the various rate types available ("Adults", "Children", "Double room" etc) plus the minimum and maximum number of customers.
Check Tour Availability
Check live availability for the chosen product, rates and number of customers.
Requesting a Booking Key
For use by Tour Operators only (Marketplace Partners should skip this step). Strictly speaking this is a step rather than a method. This step redirects the customer to the TourCMS server briefly so that any previous Marketplace affiliate clicks etc can be correctly tracked.
Start New Booking
Create a temporary booking holding off places for the customers on the product specified.
Commit New Booking
Convert the temporary booking created with Start New Booking into a live booking.
Taking payments - For Tour Operator accounts
Broadly speaking, when building a website there are two types of payment solution:
- Hosted payment page - Here you will be directing the customer to a third party website to enter their payment details and make payment, you will then receive the customer back on your website and check that the payment was successful, or perhaps receive a separate IPN style notification back from the payment processor. A common example would be PayPal.
- API / Silent post - Here you will be the one actioning the payment, via an API call once you have a token that represents the customers card details
Additionally TourCMS supports a special, deeper integration with payment gateways integrated using Spreedly, which works via a "Silent Post", JSONP or JavaScript CORS post type integration.
Details of the suggested steps to take for each of these three approaches can be found below:
> Hosted payment pages
We would generally suggest committing the booking prior to redirecting the customer to the hosted payment page, that way if there is any problem with the payment gateway after the clients money has been taken you still have a (usually Quotation/Provisional stage) booking to refer back to.
It's better to have a booking with no payment, than a payment with no booking to relate it to.
Commit New Booking
This will convert the temporary booking into a confirmed booking before you redirect the customer to the hosted payment page.
If the payment succeeds
Record a SUCCESSFUL payment / refund
Log details of the payment onto the sales ledger of a booking, reducing the outstanding balance. If the supplier has correctly configured their settings this should move the clients booking to provisional or confirmed status and trigger sending of the corresponding email.
If the payment fails (and if the gateway notifies you of that fact)
Record a FAILED payment
This will log details of the failed payment attempt into the booking audit trail, and trigger a "Failed payment email" (if one is configured in TourCMS).
> API / Silent post payments
We would generally suggest processing the payment details prior to committing the booking (i.e. after Step 4 - Start new booking).
If the payment fails
We would generally tour operators either show the client an error message and allow them to make another payment attempt or commit the booking and record the failed payment - depending on business preferences.
If the payment succeeds
Commit New Booking
This will convert the temporary booking into a confirmed booking, you should set suppress_email to 1 so that no new booking email is sent.
Record a SUCCESSFUL payment / refund
Log details of the payment onto the sales ledger of a booking, reducing the outstanding balance. If the supplier has correctly configured their settings this should move the clients booking to provisional or confirmed status and trigger sending of the corresponding email.
> Spreedly-integrated payment gateways
Spreedly is a third party service that integrates with many payment gateways at once. Integrating with Spreedly allows TourCMS to support many more payment gateways than it would otherwise, and to provide more advanced functionality such as refunding from within TourCMS itself.
To present a payment form to the client simply follow the Spreedly documentation for "Silent post" style payment form, JSONP request or CORS post. That will store the card in the Spreedly Vault and return you a token that can be used to charge the card in the next step.
Rather than committing the booking there is an alternative Step 5 to use when working with Spreedly payments, once you have a token representing the customers credit card just call:
Spreedly Create New Payment
Pass the Spreedly payment method (credit card) token to this API method to take payment. If successful TourCMS will commit the booking (if not already committed) meaning you don't need to call "Commit new booking" - and store details of the payment on the booking, potentially changing the booking status at the same time.
If the payment fails
Show the client the error that comes back from TourCMS and allow them to make another payment attempt. Alternatively commit the booking and record the failed payment.
If the payment succeeds
There's nothing else to do. Spreedly has taken payment, TourCMS has committed the booking (if it wasn't already committed) and updated the booking, storing the payment in the ledger and updating the booking status (if the channel is configured to change status on payment).
Taking payments - For Agent/Affiliate accounts
"Retail agents"
TourCMS classes retail agents as those taking the payment from the client, then separately paying the tour operator - less their commission.
If you are working on this basis, when you commit a booking to a tour operator:
- If you are configured by the tour operator as a "Trusted travel agent" your bookings will enter the tour operators system as immediately "Confirmed", at which point the client may immediately have any vouchers etc issued.
- If you are configured as regular retail agent then your bookings may initially go in to the tour operators system as a "Quotation" or "Provisional" booking, until such time as they make the booking "Confirmed" and issue confirmation / vouchers (perhaps when they receive your payment).
"Affiliates"
TourCMS classes affiliate relationships as the lead customer paying the balance, with the affiliate likely receiving reimbursement from the tour operator in the form of listing fees and/or commission.
Traditionally, affiliate type relationships have had to work whereby the travel agent sends the customer to the tour operators website to book, or for the affiliate to rebrand the standard TourCMS booking engine which uses the tour operators payment gateway of choice to handle payments.
Spreedly
A new option is now available for affiliates thanks to TourCMS integration with Spreedly. When working with tour operators that are configured to use a gateway integrated via Spreedly, affiliates can obtain a Spreedly Environment key for the tour operator in question, allowing them to build a client side payment form either using Spreedly's "Silent post" style payment form, JSONP request or CORS post (limiting PCI scope) then replace Step 5 of the TourCMS API booking process mentioned above with:
Spreedly Create New Payment
Pass the Spreedly payment method (credit card) token to this API method to take payment. If successful TourCMS will commit the booking (if not already committed) meaning you don't need to call "Commit new booking" - and store details of the payment on the booking, potentially changing the booking status at the same time.
If the payment fails
Show the client the error that comes back from TourCMS, perhaps allow them to make another payment attempt.
If the payment succeeds
There's nothing else to do. Spreedly has taken payment, TourCMS has committed the booking (if it wasn't already committed) and updated the booking, storing the payment in the ledger and updating the booking status (if the channel is configured to change status on payment).
Optional steps / other things to consider
Show Tour Dates & Deals
If you are building a user facing booking system this could be used at the start of the process to get the possible start dates, perhaps to populate a calendar control (use the distinct_start_dates parameter).
Show Promo code
Check if a promo code is valid for a given channel without having to create a booking. Also lets you know if a promo code requires a membership number to be provided and if so, what format it takes.
Customer update
If you need to supply customer details subsequent to booking start, but prior to booking commit, you can update the customer records (e.g. with correct names and addresses)
Add a note to a booking
Add a general log, note or modification request to a booking - great for agents sending through customer change requests
Delete Booking
Currently only supports deletion of temporary bookings created via Start new booking, useful as a way to release stock held on a temporary booking that is no longer required. Temporary bookings are automatically deleted after a short while anyway, this just speeds up the process.
Show Booking
Retrieve details of the newly created booking, perhaps to show some details to the customer once their booking has been completed or to send in an email if you are doing so manually rather than relying on TourCMS automated emails.
Show Channel
Retrieve information regarding the channel the Tour is being booked with, includes the terms and conditions (which you may need to display to the customer).