TravelCaster API - Flights - BookFlight operation

Back to Flights home.

After you have confirmed the selected options and the flight fare, you will need to send the passengers' data in a booking request. If the booking succeeds, the API will return the resulting booking number and then the process will be complete.

The BookFlight operation uses the FlightBookingRequest returned by the ConfirmFlightAvailability or GetFareOptions as a starting point to finishing the flight API flow, resulting in a successful booking. Based on the returned data, you just have to add passenger identification data and buyer information and send that data to the BookFlight operation, which will return a FlightBookingResponse object with a booking number. To call this operation you will need a valid token, obtained previously with the GetAccessToken operation. If your token is no longer valid, you will receive a 1210 error. See the Transaction Codes page for more information.

Request

JSON

http://endpoint/api/version/FlightService.json/BookFlight [POST]

url-encoded parameter: booking([FlightBookingRequest])

returns: FlightBookingResponse

WebService

http://endpoint/api/version/FlightService.asmx

operation: BookFlight

parameters: booking ([FlightBookingRequest])

returns: FlightBookingResponse

Structure of the FlightBookingRequest object

FlightBookingRequest
 |
 |_ Token (string)
 |_ TransactionID (string)
 |_ TransactionCode (string)
 |_ TransactionMessage (string)
 |
 |_ RecommendationID (string)
 |_ BookingFare (FlightFare object - see [GetFlightAvailability](operation-getflightavailability) for structure)
 |_ Passengers (PaxInformation[])
    |
    |_ Number (int - 1-based index of this passenger in the array)
    |_ LastName (string)
    |_ FirstName (string)
    |_ DateOfBirth (string - ISO 8601 YYYY-MM-DD format)
    |_ Gender (string - MR, MS, MRS)
    |_ RequiredInformations (AdditionalBookingInformation[])
       |_ FieldName (string - code for required information for this passenger, see reference below)
       |_ FieldValue (string)
 |
 |_ CreditCardInfo (CreditCardDetails - optional, according to your API access)
    |
    |_ NameOnCard (string)
    |_ CardNumber (string)
    |_ SecurityCode (string - subject to ticketing arrangement with your TravelCaster partner)
    |_ AuthorizationCode (string - subject to ticketing arrangement with your TravelCaster partner)
    |_ IssuingBank (string - subject to ticketing arrangement with your TravelCaster partner)
    |_ ExpirationDate (string - YYYY-MM format)
    |_ CardType (string - VI, AX, EC, CA)
    |_ Installments (int - optional, according to the supplied credit card restrictions, see below)
 |
 |_ Buyer (BuyerInformation)
    |
    |_ LastName (string - mandatory)
    |_ FirstName (string - mandatory)
    |_ TelephoneCountry (string - mandatory - phone country code)
    |_ Telephone (string - mandatory)
    |_ Email (string - mandatory)
    |_ City (string - mandatory)
    |_ Country (string - mandatory - 2-letter ISO 3166-1 code)
    |_ StreetAddress (string - optional)
    |_ ZipCode (string - optional)
    |_ State (string - optional)
    |_ Document (string - optional - Fiscal ID)  
 |
 |_ RequestedAncillaries (RequestedAncillary[])
    |
    |_ OfferType (string - code use for the Extra)
    |_ OfferData (string - mandatory code for provider)
    |_ PassengerNumber (int - passenger number as supplied in the Passengers array)
    |_ SegmentNumbers (int[] - Segments numbers as informed in the selected flight options)
    |_ Quantity (string - Used for requesting Ancillary-Bag. At the moment you can only request 1 extra bag, so indicate "1" as value)
    |_ SeatRowColumn (string - Used for requesting Ancillary-Seats)
    |_ ExpectedTotalPrice (decimal - expected total price of the requested ancillary, in the same currency of the booking fare)
 |_ BookingExternalID (string - *new in 1.6* - external ID linked to this booking)

Response time

Some providers can take up to 60 seconds to response a booking transaction, you must set TimeOut for BookFlight transaction to 65 seconds. A good practice is to implement the ListBookings transaction at the end of the day for verifying all the booking reservation statuses.

BookingFare

Use the entired BookingFare received into the previous transaction (ConfirmFlightAvailability or GetFareOptions). Clone this object (BookingFare) without modifiying the information.

If the previus transaction is GetFareOptions and you will try to book one of the provided "AlternativeFares",use the Booking.BookingFare to complete the the selected alternative and provide it into the request.

  • AlternativeFares[selectedIndex].FareID ← Booking.BookingFare.FareID
  • AlternativeFares[selectedIndex].Legs ← Booking.BookingFare.Legs

Passengers

Clone and complete the received passenger structure. It is important to maintain the passenger's order and type. You will have one PaxInformation object for each passenger. If you queried 2 adults, you will have 2 PaxInformation items.

Passengers.RequiredInformations

"Some airlines for some offers" requires additional info which needs to be provided at booking time. Depending on it, the services ConfirmFlightAvailability and GetFareOptions return the required FildNames.

FildName alternatives:

  • NATL - Nationality: passenger nationality, in ISO 3166-1 alpha-3 format.
  • FOID - Form Of Identification: national ID (NI) or passport number (PP). We recommends to specify NI or PP.
  • DEXP - Document expiration date, in ISO 8601 format (yyyy-mm-dd).

Some Airlines does not Issue the Ticket if they don´t receive the required information. Other, does not Issue the Ticket if they receive more than the expected information. Because of it, we recommend only to provide the required information.

Frequent Flyer

This functionality introduces de FQTV information into the reservation. It does not verify if the airline confirmed or rejected it.

This information shoul be introduced at the booking time, by passenger, into the Passengers.RequiredInformations as the following example:

"RequiredInformations": [
	{
		"FieldName": "FQTV-CARRIER",
		"FieldValue": "AR"
	},
	{
		"FieldName": "FQTV-NUMBER",
		"FieldValue": "11223344"
	}
],

Supported providers:

  • NDC: IB, BA, AA, LH, AV, CM, LA.
  • Amadeus NDC (NDX): AV, AA.
  • Direct connection: AD, G3.
  • GDS: AMS, SBR.

Buyer

The following fields are mandatory:

  • LastName (string)
  • FirstName (string)
  • TelephoneCountry (string - phone country code)
  • Telephone (string)
  • Email (string) - In GDS providers, if CTCE was not specified, this email is set to the first passenger CTCE.
  • City (string)
  • Country (string - 2-letter ISO 3166-1 code)

Passenger contact - SSR CTCE and SSR CTCM

This functionality introduces de SSR CTCE and/or SSR CTCM information into the reservation. It does not verify if the provider confirmed or rejected it.

This information shoul be introduced at the booking time, by passenger, into the Passengers.RequiredInformations as the following example:

"RequiredInformations": [
	{
		"FieldName": "CTCE",
		"FieldValue": "pax@email.com"
	},
	{
		"FieldName": "CTCM",
		"FieldValue": "5491144556677"
	}
],

Form of payment

  • Cash payment: Do not introduce FOP information and will default to CASH.
  • Card payment:
    • The previous transaction (ConfirmFlightAvailability or GetFareOptions) returns a list of applicable credit cards for the payment of the booking. This applies to certain fares, so the field on the response might be empty in some cases. When applicable, the response will include one or more applicable credit cards, each one detailed with the bank and/or sale-action name, card-type and the different choice of installments. When available/applicable, you will also get a list of BIN numbers to which these conditions apply, and a surcharge if the bank/card applies any interest/financial cost to the transaction. Both the BIN numbers and the installments are comma-separated, e.g. you could pay with American Express (AX) in 3,6,9,12 installments for the following BINs: 374754,374755,374756.
    • The list of applicable credit cards is returned as part of the flight confirmation, prior to the booking. This information should be used to limit the choices of the end-user at the time of selecting a payment method. An empty list of applicable cards means all cards are applicable. When the booking is processed as part of the BookFlight operation, the supplied payment method is again checked against the applicable cards and a 1503 error is returned when the payment method is unmatched.
    • This information requirement depends on the agreement regarding API access with your TravelCaster partner. Please contact your TravelCaster partner if you have questions about this.
  • Update the payament information after BookFlight transaction: If you get the payment information after booking time. You can update payment methods on a booking with the UpdateBookingPayments operation.

Requested ancillaries

You can request ancillaries at the time of the booking. Check FlightAvailabilityConfirmationResponse for the Catalog of Ancillary.

If the passenger decides to book one or more of the alternatives previously shown, you will have to provide the requested ancillaries into the RequestedAncillaries by ancillary.

  • OfferType (string) ← AncillaryOffers.OfferType
  • OfferData (string) ← AncillaryOffers.OfferData
  • PassengerNumber (int) ← AncillaryOffers.PassengerNumber
    • The ConfirmFlightAvailability transaction returns a list of allowed passengers for each AncillaryOffer. As the BookFlight transaction receives the information by passenger, you should duplicate the object if you want to reserve the same ancillary for two passengers.
  • SegmentNumbers (int[]) ← AncillaryOffers.SegmentNumber
    • Reference of applied segments (consecutively, not by leg).
  • ExpectedTotalPrice (string) ← AncillaryOffers.Price

Booking external ID

Starting with API 1.6 you can provide an external booking ID to link with your system. That ID can then be retrieved and linked with on several reports. If you don't provide the ID at the time of booking, you can always update it later using the UpdateBookingExternalID operation.

Structure of the FlightBookingResponse object

FlightBookingResponse
 |
 |_ Token (string)
 |_ TransactionID (string)
 |_ TransactionCode (string)
 |_ TransactionMessage (string)
 |
 |_ BookNumber (string)
 |_ BookingExternalID (string)
 |_ BookingFare (FlightFare - see FlightRecommendation for structure)
 |_ Passengers (PaxInformation[])
    |
    |_ Number (int - 1-based index of this passenger in the array)
    |_ LastName (string)
    |_ FirstName (string)
    |_ DateOfBirth (string - ISO 8601 YYYY-MM-DD format)
    |_ Gender (string - MR, MS, MRS)
    |_ RequiredInformations (AdditionalBookingInformation[])
       |_ FieldName (string)
       |_ FieldValue (string)
 | 
 |_ BookingFareRules (string - list of fare rules applied to this booking in plain text)
 |_ FinalCurrency (string - [Issuing currency])
 |_ FinalCurrencyRatio (decimal)

Notes

  • Dates sent to and from the API are all string-based and in the YYYY-MM-DD ISO-8061 format.
  • On flight fares where specific payment methods apply, be sure to supply a combination of credit-card type/number that honors the restrictions informed in the AllowedCardPayments field in the prior step to the booking. When the booking is processed as part of the BookFlight operation, the supplied payment method is again checked against the applicable cards and a 1503 error is returned when the payment method is unmatched. New

Transaction status

  • TransactionCode: When a transaction had no errors, a null value will be returned. Any value different than null means something went wrong in the API. See the Transaction Codes page for a list of possible codes.
  • TransactionMessage Depending on the transaction, it could provide you a more granular error description that the one from the TransactionCode by itself.

Download Postman Collection with full request/response data for JSON version.

Back to Flights home.

See change history for this file
Loading...