NAV Navigation

Kyte Integration Guide (short version)

Kyte is designed to be a one-stop shop for flights and ancillaries, to be used by both leisure travel agencies and TMCs alike and as such it offers a large number of options. The API is designed in such a way that it will work with a minimal number of parameters, so you can safely ignore options you don't need.

Getting started

To help you get started with integrating Kyte, we have prepared a series of Postman sample requests, which can be found here.

After you download the samples, make sure you import both the collection and the environment. After that, replace API_KEY with your API Key in the environment and you can start making requests.

Environments

NOTE: While Kyte offers all of it's functionality in the sandbox, this in turn relies on test environments offered by airlines for this purpose. These test environments don't always have complete flight schedules (in some cases, you might get offers for flights and not be able to book them, for example)

Kyte offers two working environments for our partners: a sandbox and a live environment. The sandbox has all the functionality of our live environment, but does not cause any side effects in real life, so you can do as many bookings as you like without any issues (although some airlines throw an error if trying to book the same passenger on the same flight more than once).

Once you have received your Sandbox API key, you can start making requests to Kyte. The base endpoint for the Sandbox environment is specified in the API Reference, while the base endpoint for our Live environment will be sent to you along with a Live API key as soon as you finish Sandbox integration and you are certified for production.

Making Requests

Kyte supports only HTTPS requests and always requires an API key. In order to authenticate your requests, you need to send your API key in the request headers under x-api-key.

As with almost anything these days, content type is application/json.

While not mandatory, you can supply two additional headers to any request:

Even if these two headers are not specified when making a request, Kyte will generate a UUID for them and they will always be present in the response headers. This way, if you have trouble with a request, you can quote its RequestId to help us identify it. However, we do recommend setting these headers on your side, especially if you have trouble with a request towards the end of the booking flow (if we have the same TransactionId across all requests, we can get a better picture of what happened up to that point)

Common concepts

API Keys and Applications

One API key is tied to an Application on Kyte, which in turn holds a set of airline credentials for you. There is no limit to the number of applications you can have, allowing for more fine grained control of credentials used - thus, you can create multiple applications for multiple agents or locations if needed.

However, when working with the Sandbox you only need a single application, which will be automatically created for you.

Each API key also links to a list of enabled airlines, so that any request will only query airlines on this list, avoiding unnecessary trafic and system overhead for API users that do not need content from every airline.

Contexts

Kyte uses the concept of "contexts", to express the general state in which a request is executed - think of them as extended sessions if you will. Some API calls can be executed in only one context (meaning you need to have the proper Id), while others can be executed in all contexts.

There are two possible contexts at the moment:

PossibleAction API

Every response you receive from Kyte will contain a possibleActions field on the root object, which lists the next valid API calls that can be called after this. Each entry is a dictionary keyed by the airline code and an id for the actual action (since two or more airlines can share the same action). These actions are available in a separate list named actionList (again, on the root object). Every action includes the time by which it needs to be called, whether it's mandatory or not, and applicable options, such as what ancillaries are supported. This information is designed to offer you a machine readable way to customize your UI/UX without having to add distinct logic for any particular airline (ie.: you can disable or hide the seatmap button if the airline/fare class does not support seat selection)

NOTE: if any ancillary type is mandatory, the whole ShopAncillaries call will be mandatory.

For example, if you do a search for flights, you will receive a list of endpoints like OfferDetails or ShopAncillaries and a specific action for each airline that returned offers. If you want to continue the booking flow for an airline, you can look at each endpoint entry, under the selected offer(s') owner and then use the action id to find the appropriate actions in the actionList. If you're looking at an action associated to ShopAncillaries you will also see a field called requestedItems which contains information on the available ancillaries for that offer/airline and if they're mandatory or not.

Errors and Warnings

All responses from Kyte follow a common structure, which includes (albeit optionally) a list of errors and a list of warnings. As much as possible, our services tries to discover all possible errors at once instead of sending back only one error at a time (we're developers as well, we know how annoying that is). Some errors and warnings are passed on from the airline, so make sure you always have a look at them, as they may contain important information.

Item referencing

    const flight = flights[flightId]

    // instead of

    const flight = flights.search(flight => flight.id === flightId)

Due to the complexity and amount of the data involved, Kyte data objects will often reference other objects instead of including them directly, to avoid duplication. When initially supplying these objects, we have chosen to use "dictionaries" instead of "arrays", thus allowing for quick and easy retrieval.

Searching for flights

NOTE: while the API allows this (for future use), we do not support flexible date searches yet. This will be available in a future release.

Searching for flights between two or more destinations is done using the Shop Flights API Call. This allows you to specify a list of Journeys, where each Journey represents an origin point, a departure point and a departure date. If you need to do a search for a round-trip flight, simply add two Journey objects in this array. Multi-city/open-jaw searches are also possible, subject to airline support.

NOTE: Airlines treat such options differently, so expect parameters such as cabinType, fareType and aircraftPreference to be used more as guidelines. In some cases, specifying a cabin type will return offers for that cabin type and one class above (but never below).

NOTE: While a fareType of low can be specified, most full-service airlines do not offer support for such queries (even though they do have fares classified as low). In these cases, your option of low will be mapped to lowest, but depending on availability you may actually receive low class fares (they will be marked as such in the fare details of an offer)

Additional options allow for specifying if you require only non-stop flights, a particular cabin type, flexible or lowest pricing and a list of passengers (minimal information is required, but we do encourage you to specify the age of the passenger, as this might translate into better pricing on some airlines).

NOTE: Frequent Flyer accounts can be specified per passenger, while Business accounts are specified per search request. If multiple passengers have an account for the same provider, they will all be passed on, but account selection will be made by the airline. As such, there is no guarantee the best one will be chosen, although usually this is the case.

Last but not least, you can specify a list of Frequent Flyer and Business accounts. Kyte will match them to supported airlines and only pass the correct information to an airline - if multiple accounts are specified for one airline, only the first will be used.

Kyte will respond with a series of matched JourneyLegs (each essentially a Journey with an Id and a list of flights that services this route), a series of individual flights and a series of offers. Each offer will cover all requested Journeys, so no manual matching/grouping must be done. At the same time, an offer might not fully match your requested cabin type for all flights (in cases where two or more journeys were requested, but the cabin type is not available for all flights resolving this journey configuration you might receive a partial match).

While you can always search using city codes, if you don't care for a specific airport, some airlines (British Airways for example) will do this by default. If you do need the specific airport(s) your requested make sure the exactMatch flag is set to true. This will filter out any flights that do not match your exact search (a word of notice: using exactMatch: true and city code searches will never yield any results)

Each offer contains full price, breakdown by passenger (with subsequent breakdown into base fare and taxes/surcharges), currency and a set of one or more fares, each containing a description of the perks (and/or limitations) associated with it.

Searching for Bundles

Please note, this call is only available for low-cost carriers.

For low-cost carriers, you can shop for bundles using the ShopBundles to quickly add bundles (combination of ancillaries) offered by the airlines to any booking. The bundle offers are subject to availability and based on the options provided by the airlines.

To shop for bundles, please use the offerId from shop flights to get the bundle offers. The response will include the new offerId for bundles, description of the bundles, fares and the passengers that it can be applied to. From this stage, you can switch to using the new offerId received in the response of ShopBundles to proceed with collecting pax information.

The bundles should only be called for a single offer. Once you choose to ShopBundles, a new offerId is provided for each bundle. There are currently no restrictions to call for ShopAncillaries once the booking is created and a bookingId is generated.

Getting offer details

NOTE: While this API call is not mandatory to create a booking, we recommend you do call it and display the information to customers.

If you are interested in more details regarding an offer, you can use the Offer Details API Call to request more information on up to 5 fares (for comparison purposes).

Kyte will respond with a set of disclosures for this offer, detailed baggage allowance and servicing fees. All of these items contain a list of references for both applicable passengers and applicable flight segments.

Getting available ancillaries

NOTE: If you need more than one type of ancillaries, please add them to the requestedTypes field in the request instead of making multiple calls.

Retrieving the list of ancillaries is done through the ShopAncillaries call. To make this as efficient as possible, you can request only the types of ancillaries you actually need.

This API call can be executed both in the context of an offer and in the context of the booking by passing the correct Id as a path parameter. Kyte will automatically detect which context the Id refers to. It is recommended that once a booking has been created, Shop Ancillaries is only called in the booking context, even if the offer context is still available.

Making a booking

Starting from a non-expired offer or Bundle offer, you can create a booking through the Book Flight call. At this point, you will need to pass on the complete passenger information.

NOTE: Booking will be valid until the Ticket Time Limit, after which no further operations can be executed on it, except for OrderRetrieve

If successful, booking information will be returned and it's status will be notTicketed. This means no tickets have been issued for this booking, awaiting payment. Alongside this, a list of accepted payment methods will be specified as well.

At this point, you can add ancillaries to this order (which will update the total amount and the current balance) or simply make a payment and issue eTickets and EMDs (where applicable).

Adding ancillaries

Adding ancillaries to a booking can be done through the Book Ancillaries call. As pre-requisites you need to have a valid booking and to have called Shop Ancillaries either in the offer or booking context.

Calling this will update the status of the current booking, without issuing any tickets. As a result, you can add, change, remove ancillaries without commiting the changes to the airline. When happy the final configuration, you can use the Payment call to arrange payment and issue tickets (if successful).

After each call to Book Ancillaries, the response will contain the current state of selected ancillaries, per passenger, for validation. This includes the state of each individual ancillary, where:

Payment

NOTE: Partial payments or multiple payment methods are not currently supported, but will be added in a future release.

NOTE: If the card used for payment does not belong to one of the passengers, you need to pass the payerInformation field as well, specifying the contact information for the owner of the card.

Submitting a payment request for a valid booking is done through the Payment API call. Depending on airline support, payment can be made through either:

Payment amount will be validated again with the airline and if any changes in pricing appear, this call will fail and report back the change, preventing incorrect charges.

NOTE: Kyte does not charge cards. Their details are passed on to the airline directly and they are not stored in our system at any time.

Below is a list of test cards that can be used in the sandbox:

  • Easyjet (standard): 4444333322221111, visa expiring 03/30, CVC: 737
  • British Airways (standard): 4263930000007395, visa expiring 10/30, CVC: 747
  • American Airlines (standard): 345678000000007, amex expiring 01/30, CVC: 747
  • Iberia (standard): 4012999999999999, amex expiring 12/30, CVC: 491
  • Air Canada (standard): 4012999999999999, visa-debit expiring 10/30, CVC: 747
  • Qatar (standard): 4539795097006388, visa expiring 12/30, CVC: 747
  • Finnair (standard): 4147200022000006, visa-debit expiring 12/30, CVC: 747
  • Ryanair (standard): 5210000010001001, mastercard expiring 12/30, CVC: 747

If successful, this will issue all tickets (eTickets and EMDs) for this booking, returning the status ok. Make sure there are no warnings attached to this response, however. If you want to get an updated view on the booking, you can use the Retrieve Booking functionality, presented below.

3DSecure

Version 1

Version 1 of 3DSecure is still supported by some airlines and by Kyte as well, although it is recommended to migrate to version 2 as soon as possible/feasible.

In this version, we recommend you always send the responseURL parameter so that a proper challenge can be formed if the card is enrolled. The URL passed here should accept POST requests, as it will be called by the MPI handling the transaction.

In case of card payment where the card is enrolled, Kyte will respond with a challenge, after which you will need to call this endpoint again with the challenge response. The challenge will be a dictionary of values that need to be included as hidden fields in an HTML form that should be automatically submitted. This dictionary will always contain a key named redirectUrl which should be used action property of the form (and not as a hidden field). Alternatively, if the codegen parameter was set to true, you will receive the HTML code for this form in the response.

Note: The same card used in the initial request must be send in the second request, otherwise it will return an error. Kyte does not store the initial card, but a hash of it, for validation.

Once the user inputs their password or OTP, the challenge response will be sent to the responseURL that was submitted in the first payment request. Using that value, another payment request should be made to Kyte to finalize the process (this time using challengeResponse as method, instead of card).

Version 2

Version 2 of 3DSecure is supported by most (soon to be all) airlines, but requires additional integration work on the API user's side. Namely, you (as the actual interface with the user) are now responsible for the authentication part of the flow, while the airline's PSP will handle the authorization.

Before attempting to call the Payment endpoint, you must authenticate the user's card through your own PSP, which will issue challenge if needed (similar to the 3DSv1 flow). After the user successfully resolves the challenge, you will receive the authentication data from the PSP.

This data must be added to the Payment request using the authentication field. No further challenges will be issued past this point and, assuming authentication data is correct, the payment will be processed directly.

MOTO (mail order / telephone order)

If you are creating the booking on behalf of the actual traveller(s), as a TMC, you can specify that the payment is of the MOTO kind through the transactionType field, which will bypass 3DS validation and charge the card directly. Do note that this should only be used if you are an agency using the customer's card with approval, as you will be liable for any chargebacks if said customer does not recognize the payment.

Retrieve a booking

This can be done at any time after creation by calling Retrieve Booking.

Some information is retrieved by default (eg: status, currency, total cost, ticket status), but other information must be specifically requested. Do note that some information regarding a booking might reference other information (tickets will reference a passenger Id, for example), but this information is not automatically retrieved. As such, if you request ticket details and you want to associate them to actual passengers we recommend requesting passengerDetails.

Post Ticketing Features

Order Reshop

Reshop can be used when a traveler wants to make a change to ticketed confirmed bookings. Order Reshop allows users to change date/time, change route (currently not supported) or upgrade the cabin of their confirmed flight. The service checks the eligibility of existing booking for change/upgrade and then returns the offers for the changed date, route or upgrade cabin. This service can only be used on existing ticketed bookings made using the Kyte API, and may only be accessed by the agency who created the booking.

Change of date and time

Reshop can be used to change the date and time of a flight on the onward or the return journey. Once the new date parameter is passed when calling Reshop, the response will have all the flight options provided by the airline. Each option will have an offerId that can be used to complete the booking process.

The following scenarios can be managed through Reshop

Change of Cabin

In order to change the cabin or upgrade, the “cabinType” must be passed in the Reshop call along with the date, departureAirport and arrivalAirport. The offer will have the new OfferId along with the Price for the upgrade. The updated OfferId must be used to complete the upgrade. The payment for the change in fare must be made to complete the upgrade.

Add / remove Ancillaries

Reshop can also be used to add or remove ancillaries such as bags, seats, meal requests and sports equipment where supported by the airline.

Add Ancillaries

Use the booking ID as the parameter to add ancillaries per segment. Multiple ancillaries can be added for multiple passengers while making the book ancillaries request. The response will show the status of the ancillaries and the price if paid ancillaries were selected. Payment must be made in order to confirm the addition of paid ancillaries.

Remove Ancillaries

Ancillaries that were added during the initial booking process, can be removed using the same API service. In order to remove any ancillaries, use the ancillaries Id, type, quantity and segment and change the “action” type to ”remove”. This will remove the ancillaries that were attached to the booking.

Add Wheelchair service

Adding a wheelchair service is available through Shop and BookAncillaries. This service can only be added once the booking is created. The request type during the shop ancillaries call should request for “disabilityAssistance”, the response will have the “disabilityAssistance Id’ and the passengers Id that it can be added to.

Limitations:

Origin and destination of the same O&D cannot be changed in single transaction. Origin or destination cannot be changed to a US route from non-US route when DOB and gender is not provided in the original booking. Origin or destination cannot be changed when the same cabin doesn't exists in the new route. E.g. Premium Economy - longhaul to short haul. Paid Bag and Seat EMDs are currently not carry forwarded to the new flights after a route change. Re-routing capability is currently not available for held bookings.

Order Reprice

Order reprice will be a detailed breakdown of price changes, including services and seats, when rebooking the itinerary with the airline.

Split PNR

A PNR with multiple passengers in a single booking can be split into different PNR’s. Using the relevant booking ID, pass the paxId’s of the passengers that need to be split into a new booking. If there are children or infants in a booking, they should be added with at least 1 adult passenger while splitting a booking. In the response of the splitBooking request, a second bookingId is generated for the passengers that were split along with a new PNR. Both bookingID’s must be stored and used as required in order to make further changes to the booking or adding any additional services.

Change Held Booking

Held booking helps to confirm a PNR with the airline, without having to make a payment. It is however subject to change as per airline discretion. This call should be made after the book flights API call. The ticket status of the booking will be “notTicketed”.

Passenger Servicing

Passenger servicing allows one passenger servicing per PNR at a time. This includes the below passenger servicing that can be made to a PNR.

Name Corrections:

Each airline may have a different policy for name change. For example BA allows only 3 character changes in the name, which includes the title, first name, middle name and last name. Airlines only allow 3 character changes which includes the title, first name, middle name and last name.

Add passport details and or contact information

To add additional information to a passenger, retrieve the booking, add the paxId along with the information that needs to be added such as contactInformation or apisData.

Order Change Notifications(OCN)

OrderChange Notifications are notifications received from the airlines for various types of flight disruption. Some of the disruptions may be treated as minor and some as major. The OrderChange Notification message will be sent for disruption events (both planned and operation events). Airlines usually send notifications for the following events.

Disruption Type

The OrderChange Notification message will have a message to identify the type of disruption. The message will indicate disruptionType as ‘flightCancelled’, “scheduleChanged”, "scheduleChangeFlightCancelled", "scheduleRetimed" and ”ssrModification".

Registration Requirements

Please send us the registration information to complete the set up, the details we require as follows

Common workflow examples

Coming soon!

Troubleshooting

Kyte tries to be as descriptive as possible when encountering an error, sending both an error code and a textual description. If this is not sufficiently clear and you need help in figuring out why an API request is failing, please send us a log containing your request and the response you have received at support@gokyte.com, making sure to mask/remove all personal information from it.