XML Bookings and Handling Guide


Disclaimer:
All flight details must be checked, at each stage, by the client system and by the end traveller. TF does not take responsibility for any changes in details that are not noticed, since this can sometimes be caused by the supplier.

The ProcessTerms Request

The ProcessTerms request performs three main functions:
  • The submission of any profile details not yet submitted
  • The extraction of any final information from the supplier's website, some of which can only be obtained with the full profile details (e.g. card charges)
  • The generation of a Travelfusion booking reference. A booking record is created in the Travelfusion database, with a unique TFBookingReference. All the details of the booking are stored even though the booking has not yet been executed. This TFBookingReference should be recorded by the customer before starting the booking.
Multiple term requests should not be submitted for a particular session unless a data validation error is returned (necessitating a correction to the data and resubmission of the ProcessTerms request).

The OutwardId and ReturnId must always be submitted at ProcessTerms. However, the flight booked will be the one specified in the most recent ProcessDetails request.

The Booking Process

The StartBooking request instructs the Travelfusion engine to begin the booking process. Once this is submitted, the booking cannot be stopped. The StartBooking request will respond immediately to confirm that the booking has been started. Whatever response is received, you should assume that a booking may have been made - even if an error response is received or no response at all. From then on, the CheckBooking request must be submitted every few seconds until the booking attempt is completed. See the  CheckBooking response specifications for more details. If the booking does not complete within a reasonable time (e.g. a few minutes), the customer should handle this booking as Unconfirmed (see table below). 
It is very important to handle the booking process as defined in these pages. We have also included a booking flow diagram to explain the process.

Credit Card Verification

Some merchants/ suppliers require credit/ debit cards to be verified by the card issuer (E.g. 'Verified by Visa' or 'Mastercard Securecode'). This involves forwarding the customer to a URL operated by the card issuer (Visa / Mastercard etc). The user then enters a password on the card issuer's website and is then returned to a URL of your choice. The mechanics of this process are explained in full in the Credit Card Verification Handling Guide.

After Booking Completion...

Once the booking attempt is complete, the booking will have a number of possible statuses. The following table shows these statuses and the action that should be taken. Note that if the Travelfusion system fails to respond, or responds in any way other than with one of these statuses, this should be treated as incomplete (and therefore 'CheckBooking' polling should continue as if the 'BookingInProgress' status had been returned). Please take careful note of the timeout and retry recommendations defined elsewhere in this specification. Please ask Travelfusion for more information if required.
 Status  Action
Succeeded  The traveler should be informed that the booking has succeeded and they should be presented with the supplier reference number (and optionally the Travelfusion reference number)
Failed  The traveler should be informed that the booking failed and the reason for failure should be displayed to them. They should then be given the opportunity to amend their details and try to make the booking again as the reason for failure may be related to the details they entered (e.g. card declined by supplier)
Unconfirmed  The traveler should be informed that their booking may or may not have been made and that they should wait to be updated by email or phone, and to contact customer support if they require further assistance. Meanwhile, the CheckBooking request should continue to be submitted at a reduced frequency (every few minutes). This should continue indefinitely until the status changes to either Failed or Succeeded. Once this occurs, the traveler must be contacted to inform them of the status of their booking. Ideally, the XML client customer will handle all such customer support. Your customer care team should contact Travelfusion if a booking remains Unconfirmed for an extended period of time.
UnconfirmedBySupplier  This should be handled in a similar way to Unconfirmed, except that there may be a supplier reference which may be presented to the traveler.
BookingNotLaunched The booking was not initiated and so no ticket has been issued.
Duplicate Indicates a previous booking with similar or same details was found.

'Fake' Bookings

For development purposes, a facility is provided for making 'fake' bookings. See the StartBooking request specifications for more details. This can be used to simulate a real booking without actually billing a card. It is advisable to not use a real card number for fake bookings. See the Credit Card Verification guide for advice about using the EnableFakeCardVerification element.

'Expected Price' check 

In the StartBooking request, an Expected Price must be submitted. This should be the total price that your system believes is going to be charged. Travelfusion will confirm this is correct before proceeding with the booking. If it is not correct, a DataValidationError will be returned, containing the price that the Travelfusion system believes will be booked (see the JourneyPrice element below). At this point it is recommended that you do not complete the booking process and you investigate the problem immediately as it probably represents an error in your interpretation of Travelfusion's pricing information. However you may choose to display the 'JourneyPrice' to the user and allow them to resubmit the booking request if they are happy with this price. Travelfusion does not take responsibility for any business consequences of doing this without any investigation of the cause of the problem.

Example StartBooking request (note that in the ExpectedPrice element, only one Amount and Currency should be submitted. No other information such as tax or passenger breakdowns should be included):

<StartBooking>
    <XmlLoginId>*****</XmlLoginId>
    <LoginId>*****</LoginId>
    <TFBookingReference>Z1ZZOHT2Z</TFBookingReference>
    <ExpectedPrice>
        <Amount>22.00</Amount>
        <Currency>GBP</Currency>
    </ExpectedPrice>
</StartBooking>

Example StartBooking response (note the JourneyPrice element and the error attributes in the StartBooking element):

<CommandList>
    <DataValidationFailure>
        <StartBooking ecode="3-8039" etext="Booking expected price does not match the journey final price" edate="16/05/2011-12:15" millis="172">
            <XmlLoginId>*****</XmlLoginId>
            <LoginId>*****</LoginId>
            <TFBookingReference>Z1QGOHT2Z</TFBookingReference>
            <ExpectedPrice>
                <Amount>22.00</Amount>
                <Currency>GBP</Currency>
            </ExpectedPrice>
            <JourneyPrice>
                <Amount>81.78</Amount>
                <Currency>EUR</Currency>
            </JourneyPrice>
        </StartBooking>
    </DataValidationFailure>
    <GeneralInfoItemList>
        <GeneralInfoItem>
            <Name>ServerAddress</Name>
            <Value>10.0.0.63</Value>
        </GeneralInfoItem>
        <GeneralInfoItem>
            <Name>ClientAddress</Name>
            <Value>127.0.0.1</Value>
        </GeneralInfoItem>
        <GeneralInfoItem>
            <Name>StartTime</Name>
            <Value>16/05/11-12:15:38</Value>
        </GeneralInfoItem>
        <GeneralInfoItem>
            <Name>EndTime</Name>
            <Value>16/05/11-12:15:39</Value>
        </GeneralInfoItem>
    </GeneralInfoItemList>
</CommandList>