Custom Supplier Parameters Handling


Generic Parameter Types and Handling

Custom Supplier Parameters have been designed for generic handling. This means that in principle you do not need to implement specific code for each possible parameter, and when a new parameter is introduced you should not need to modify your code. In the cases of 'custom' and 'notice' types, these are not generic and each one must be handled in a special way. You should implement support for all parameters of type 'custom' or 'notice'. In principle, a supplier may change its functionality at any time to require a new non-generic parameter to be added and supported. These cases are very rare, but you should build your application in such a way that any unrecognised parameters are detected and the booking process halted - developers should be alerted in such cases as they will need to implement support for the parameter.

All these parameters should be supplied in a CustomSupplierParameterList, which can be supplied in the BookingProfile element at any stage of the search / booking process. Various other parameters can be supplied in the CustomSupplierParameterList that are not specified here as they will never appear in the RequiredParameterList since they are not designed for display to the user. The BookingProfile element is specified fully in the ProcessTerms Request specification.

There are 6 types of custom parameter and the type determines exactly how they should be handled:

Type  Meaning  Handling
text The parameter is free text for manual entry by the user.  Show the 'DisplayText' to the user and allow them to enter the value into a simple text box
 booleanThe parameter has only 2 possible values indicating positive or negative.Show the 'DisplayText' to the user and display a radio button with values 'yes' and 'no'. If yes is selected, submit value 'y' for this parameter. Otherwise submit value 'n'.
formatted_text The parameter is free text for manual entry by the user, following a specified format. Show the 'DisplayText' to the user and allow them to enter the value into a text box. Optionally, the input could be validated before submitting to travelfusion, but custom work would be needed for each parameter of this type and changes to the format would then cause validation failures. (Note that the required format will always be stated clearly to the user in the DisplayText)
 value_select  The parameter value must be selected by the user from a specific set of options  Parse the 'DisplayText'. All the text before the first ':' must be displayed to the user, along with a drop-down list. The items in the list should correspond to all the items listed comma-separated after the first ':'. Each item will consist of 2 values. The text before the '(' is the value that must be submitted as the custom parameter value if the item is selected. The text inside the '(' ')' is the value to display to the user. For example: "Please Select a Meal Type: 1(Snacks), 2(Pork Sandwich), 3(Snickers + Coke)". All leading/trailing whitespace should be trimmed from the text before the ':', and from the display and submission values within each item.
 custom  The parameter must be handled in a special way By default these parameters should be completely ignored and will always be optional. However, certain special functions are made available through this type of parameter such as Seat Options.
 notice  The parameter is used to provide data or information about various features. These parameters each need special custom handling and should not be ignored.  Each parameter has its own meaning/ value. Please read the specification for each one below. None of them should be submitted as custom parameters. They are only used to convey data/ flags. 


Generic Parameter Examples

The following table contains some specific examples of the 'text', 'formatted_text' and 'value_select' parameters. Since these can be handled generically, there is no need to list them here, but they are supplied for customers who wish to implement their own custom handling of these parameters.

 Name  Type/ Format  Description
DateOfBirth formatted_text
dd/mm/yyyy
 The date of birth of the traveller. If this is as a required parameter, it is strongly recommended that you submit the correct date of birth for all passengers. If you do not supply it, the booking may still be made with the supplier, but with an incorrect, estimated, or unspecified date of birth. Travelfusion takes no formal responsibility for this behaviour or its effect, but we will do our best to make sure the behaviour is appropriate. Please contact us if you have any concerns about a particular supplier.
PassportExpiryDate formatted_text
dd/mm/yyyy
  The passport expiry date
PassportCountryOfIssue formatted_text 
2 letter country code
  The passport country of issue
Nationality formatted_text 
2 letter country code
 The nationality of the passenger. Using 2 letter country code like "US".
 NumberOfBags
DEPRECATED
 formatted_text
An integer (0 or more)
 The number of bags to be checked in
No longer in use, please see the new luggage spec description:
"LuggageOptions"
"OutwardLuggageOptions"
"ReturnLuggageOptions"
AgentLogin  text  The travel agent login to submit to the supplier
AgentPassword  text  The travel agent password to submit to the supplier
AgentIATANumber  text  The IATA number of the user
AgentIdentifier  text  The agent identifier
UserLogin  text Preregistered username or username to be registered with on the supplier's system
UserPassword  text  Preregistered password or password to be registered with on the supplier's system
PassportNumber  text  The passport number
FrequentFlyerNumber text  The frequent flyer number
AgencyInvoiceReference text  This enables an invoice number to be supplied to the supplier for later reconciliation
AgencyPaymentPassword text This is the extra password used to identify the agency in cases where a payment account has been set up with the supplier
SpecifiedFareBasisCodeOutward text Only the outward results with the specified fare base code will be returned
SpecifiedFareBasisCodeReturn textOnly the return results with the specified fare base code will be returned
SpecifiedRBDCodeOutward textOnly the outward results with the RBD code will be returned
SpecifiedRBDCodeReturn text Only the return results with the specified RBD code will be returned
EndUserIPAddress (new) textThe IP address captured from the end user's terminal - i.e. the client that is using the website where the search/ booking is being made. It takes the format of an IP address - e.g  12.123.45.67. It is a mandatory requirement to submit this parameter in all XML requests to Travelfusion during the search and book process.
EndUserBrowserAgent (new) textThis is based on the User-Agent Http header, which identifies the unique browser and/or devise through which the booking was made. An example value could be - 'Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/21.0' It is a mandatory requirement to submit this parameter in all XML requests to Travelfusion during the search and book process.
EndUserDeviceMACAddress (new) textThe unique identifier assigned to the physical device on which the user attempts the booking. This is an optional element and must be submitted whenever the end user’s MAC address was captured.
An example value could be - '01-23-45-67-89-ab'

UserData (new) textVarious data related to the user must be submitted here, in the ProcessTerms request. The data must be comma separated and commas in the data items must be escaped with '\', as should the '\' character.
Currently, we require the end user's email address, phone number, and the card holder's name on card. For example:


bob@myemail.com, +4917182828283, Mr b t blob

Travelfusion reserves the right to request more items of data to be added to this list, with 3 months notice.
RequestOrigin (new) textThis must identify the origin of the original user search. Typically it will be the domain of the website they were using and the market/ country/ Point of sale - for example "France-cheaptravelling.com". Please discuss with Travelfusion if in doubt about how to complete this field.

It is a mandatory requirement to submit this parameter in all XML requests to Travelfusion during the search and book process.
SpeedyBoarding boolean Indicates whether speedy boarding should be requested from the supplier
OnlineCheckinWithEUPassportOrId boolean Requests online check-in from the supplier. The user will need to check in via the supplier's website. 'Hand luggage only. EU passport/ id only.
ListFareBasisCodeboolean Indicates whether fare base code should be listed in CheckRoutingResponse
ListRBDCodeboolean Indicates whether RBD code should be listed in CheckRoutingResponse
MealType value_select Specifies which type of meal the end user requires.
CheckInTypevalue_selectSpecifies which type of Check-in the end user requires.
InsuranceType value_select Specifies which type of insurance the end user requires.
FrequentFlyerType value_select Specifies which type of frequent flyer club the end user requires.
LuggageOptions (new)value_select Specifies the available Luggage options that can be purchased within a booking. An option denotes a combination of number of bags, their weight and its cost.

For example:

'Please Select Luggage Option: 1 (1 bags - 15Kg total - 25.00 EUR), 2 (1 bags - 20Kg total - 35.00 EUR), 3 (2 bags - 15Kg+15Kg - 50.00 EUR), 4 (2 bags - 15Kg+20Kg - 60.00 EUR), 5 (3 bags - 50Kg total - 90.00 EUR)'

Using the above example, by selecting option:
  • '2' - a bag of 20 Kg will be purchased with the booking.
  • '3' - 2 bags, each weighting no more than 15 Kg, with combined weight of 30 Kg will be purchased with the booking.
  • '4' - 2 bags, one of which should be no more than 15 Kg, with combined weight of 35 Kg will be purchased with the booking.
  • '5' - 3 bags with total combined weight of 50 Kg will be purchased with the booking.
    Bear in mind that the list of available options is not static and varies between bookings, therefore it should be handled dynamically. Equally, if LuggageOptions are missing completely, it should not be assumed that a default bag is included in any of the fare types.

    
Depending on the booked airline, luggage selection can be either on per leg basis or for the entire booking. If the latter, this parameter will be returned, otherwise the selection will be broken down using the following parameters: 'OutwardLuggageOptions' and 'ReturnLuggageOptions'.

    Please note that on a round-trip booking with luggage selection on per leg basis where only one of 'OutwardLuggageOptions' and 'ReturnLuggageOptions' is submitted, bags will be purchased just for the requested leg of the booking.

    To preserve backward compatibility, this parameter (
or its leg-based derivatives) will not be returned unless explicitly requested. If you wish to use it, as opposed to the existing parameters (NumberOfBags and BaggageWeight), please contact Travelfusion. Alternatively, just for testing purposes, you can submit the 'UseNewLuggageFramework' Custom Supplier Parameter with value 'true' at StartRouting which will activate it for the particular search.

    Please note that as we are in the process of incorporating this parameter it may not be available for all the suppliers you use. If that is the case, please contact Travelfusion and we will try to prioritise on them.
 OutwardLuggageOptions (new) value_selectSpecifies the available Luggage options that can be purchased for the outward leg of the booking. For more information please see 'LuggageOptions' parameter.

Please note that if this parameter is missing completely, it
 should not be assumed that a default bag is included in any of the fare types.
 ReturnLuggageOptions (new) value_selectSpecifies the available Luggage options that can be purchased for the return leg of the booking. For more information please see 'LuggageOptions' parameter.

Please note that if this parameter is missing completely, it should not be assumed that a default bag is included in any of the fare types.
 FlightExtras (new) value_selectThe following features are supported here:  
GolfBag, Skis, MusicalInstrument, Bike, SpecialAssistance

NOTE, only one of these can be selected for a each passenger.
An example of the Display Text format is below:

Please Select Flight Extras Options: Bike (Bike - 60.00 GBP), MusicalInstrument (Musical Instrument - 50.00 GBP), Skis (Skis - 40.00 GBP), GolfBag (Golf Bag - 30.00 GBP)

This format will be maintained, so if you wish, you may parse out the price and use this to dynamically update the displayed total price when the user selects an option.

   
   

Parameters With Type 'Custom'
 Name Type Description
 BaggageWeight
DEPRECATED
 customSimilar to a value_select parameters, but the items listed for selection by the user may consist of the weight of baggage only, or both weight of baggage and number of bags, e.g.:
"Please Select Baggage Weight : 1(1bags-15Kg),2(1bags-20Kg),3(1bags-23Kg),4(2bags-40Kg)
Only one of 'NumberOfBags' and 'BaggageWeight' can be submitted at a time.
No longer in use, please see the new luggage spec description:
"LuggageOptions"
"OutwardLuggageOptions"
"ReturnLuggageOptions"
 SeatOptions customThis is a compound select. After the first colon, there is a seating list for each flight with all available attributes. The flights are separated by ','. Each flight has a flight number
and then followed by a "-" separated seat numbers. all other attributes are listed in the "()". For example: "
Please Select
Seat Options:5477-1A(W|E|1A@12.00GBP@319),
5477-1B(N|E|1A@12.00GBP@319),
"
Therefore multiple drop down lists will need to be displayed to the user.
Find more details here
 UseCardPreRegisteredWithSupplier  customIndicates that the supplier supports preregistered cards. In order to use a pre-registerd card, this should be submitted with value 'true'. You will still need to supply a card in the BookingProfile, but it will not be used for the payment, so a dummy card number should be used.
 BookingOnHold customIndicates that the supplier supports the function of booking on hold. In order to achieve this, this should be submitted with value 'true'.
 UseTFPrepay customIndicates that the supplier supports TF.Prepaid for this booking. If TF.Prepaid is required for this booking, submit with value 'Always' or 'WhenApplicable', 
Using this service requires the customer to enter into a special agreement with TF. Please see detailed spec under 'Guidelines'.


Parameters With Type 'Notice'



Name  Type Effect
FullCardNameBreakdown  notice If specified, the Name on the card must be specified in full detail. See the NameOnCard element in the ProcessTerms Request.
PostCode  noticeIf specified, a postcode must be supplied in all addresses for this booking. 
BillingAddress  noticeIf specified, a billing address must be submitted for this booking (the Address element within the BillingDetails section of the booking profile.)
CardSecurityNumber  noticeIf this is specified, the SecurityCode field in the ProcessTerms Request must be submitted (it is recommended to always submit it anyway where possible).
CardStartDate  notice If specified, the StartDate field in the ProcessTerms Request must be submitted. (it is recommended to always submit it anyway if possible.)
ChildrenAndInfantsSearch  notice If this is specified, you may search for children and infants for this supplier. Otherwise, only adults are supported.
ChildrenAndInfantsBooking  noticeIf this is specified, you may book for children and infants for this supplier. Otherwise, only adults may be booked. 
DateOfBirthIsNotRequiredForAdults  notice In some of the cases where 'DateOfBirth' is returned as a required parameter, DateOfBirthIsNotRequiredForAdults may also be returned, indicating that it is only required for children and infants.
SpecialFamilyAncillaryDiscounts notice - There are 50% discounts of checked bags, allocated seats, priority boarding and travel insurance for up to a maximum of 2 children when 1 accompanying adult included in the same reservation purchases the corresponding fully priced item.
- There are 50% discounts of checked bags, allocated seats, priority boarding and travel insurance for up to a maximum of 4 children when the 2 accompanying adults included in the same reservation, purchase the corresponding fully priced item.
- Adults and children must be booked in the same reservation to receive the family discount.
- These discounts will not be reflected in the prices returned by our API at the availability and pricing step. It is necessary to apply them within your application according to the logic described above. At the ProcessTerms, such discounts will be reflected accordingly.

Please check here the Custom Supplier Parameters used by each airline. 

[For reference only, previous (deprecated) notes are provided here]

Comments