Flight Booking Flow Overview

Overview

Scenario
Mark plans to travel from Hong Kong to Singapore. He will depart on May 8 and return on June 8. He prefers Economy Class and would also like to purchase additional baggage.

To fulfill Mark’s requirements, the booking flow consists of the following steps:

Search for flights

Select a flight and optional ancillaries

Create an order

Complete payment and issue tickets

Notify the customer with PNR and ticket details

1. Search for Flights

User action
Mark enters the origin, destination, travel dates, and cabin class to search for available flights.

To initiate a flight search, you need to construct a request payload that includes:

Flight itinerary information, such as origin, destination, and departure date(s)

Passenger information

The Shopping API is used for this step.

Example – Shopping API Request

{
  "search": {
    "nonstop": 0,
    "children": 0,
    "solutions": 0,
    "adults": 1,
    "airline": "",
    "searchAirLegs": [
      {
        "cabinClass": "Economy",
        "origin": "BKK",
        "destination": "SIN",
        "departureDate": "2023-05-08"
      },
      {
        "cabinClass": "Economy",
        "origin": "SIN",
        "destination": "BKK",
        "departureDate": "2023-06-08"
      }
    ]
  },
  "authentication": {
    "sign": "111",
    "partnerId": "111"
  }
}

Shopping Response Structure

Solution: A list of available flight options with corresponding prices

Journey:

For a one-way trip, the response contains only journey_0

For a round trip, the response contains both journey_0 (outbound) and journey_1 (inbound)

For an open-jaw trip, the response also contains journey_0 and journey_1 for the two journeys

Flight: Defines the relationship between Journey and Segment

Segment: Contains detailed segment-level flight information

Notes

The sign field must be generated by combining partnerId and partnerKey, then encrypting them with MD5.

The Shopping response is delivered in GZIP format. You must decompress it before processing the data.

The Shopping request must be encrypted with BASE64. JSON format is now also supported.

The miniRule returned in the Shopping response is for reference only. If you need fare rules in text format, please call the Penalty API.

2. Select a Flight and Ancillary

2.1 Validate the Selected Flight

User action
Mark reviews the returned flight options and selects one that he is interested in.

Once a solution is selected, you need to call the PrecisePricing API to check the flight’s real-time availability and price.

You should pass all necessary journey information, passenger type, passenger count, cabin class, and other required fields from the selected Shopping solution. Since inventory and pricing are dynamic, the response will confirm whether the itinerary is still available and what the latest price is.

Example – PrecisePricing Request

{
  "pricing": {
    "journeys": {
      "journey_0": [
        {
          "airline": "FD",
          "flightNum": "501",
          "arrival": "DMK",
          "arrivalDate": "2024-12-15",
          "arrivalTime": "16:40",
          "departure": "HKG",
          "departureDate": "2024-12-15",
          "departureTime": "14:40",
          "bookingCode": "Z"
        }
      ],
      "journey_1": [
        {
          "airline": "FD",
          "flightNum": "504",
          "arrival": "HKG",
          "arrivalDate": "2024-12-30",
          "arrivalTime": "19:15",
          "departure": "DMK",
          "departureDate": "2024-12-30",
          "departureTime": "15:30",
          "bookingCode": "A"
        }
      ]
    },
    "adults": 1,
    "children": 1,
    "infants": 0,
    "solutionId": "iXf1ufZoOsBU+MpHfwQD6vzfcE3X5BFe1Vxl3oa9iNn1Noc75XschKYpLVXfU17PcPI7oU/EVSKjQj2Xuxt9QoSJGTP7oW12BBtDUQvlAzaZ1z0zhjr4N5cJVh2fElsdEXXtCGI00H3Nvx98/d2z6lUfU0Yhuny0kj/rOz4IMMmghIhWyGDa4e4T7y3BrTjFwEPZh0nHoEykVO13sMp0vXt8ub60T12OXl9dooXkhpqN51MhNjyCkSYjIYff//DJ1cRBps9+3e58SI0ifR8P6FiCKSCYOmCQLFKKLU0P8+Xlv4BsqxNY0pdOKT7LeR3w2YGgt1zSCyEXZCwy/+BBLA66j01ytAzieUvdZ3sqLyc8+7IG23vo1JfqVtlJo/pvRdlQyp6gQGJDPraSkTCSvA==",
    "cabin": ""
  }
}

For more details, please refer to the PrecisePricing API documentation.

2.2 Select Ancillary Services

Additional requirement
Mark would like to purchase extra baggage.

To support this requirement, you may need to call the AncillaryPricing API to check the availability and price of paid baggage. You can then display the ancillary options to the customer.

Example – AncillaryPricing Request

{
  "authentication": {
    "sign": "111",
    "partnerId": "111"
  },
  "pricing": {
    "journeys": {
      "journey_0": [
        {
          "departureTime": "14:40",
          "flightNum": "501",
          "arrival": "DMK",
          "arrivalTime": "16:40",
          "bookingCode": "Z",
          "departure": "HKG",
          "departureDate": "2024-12-15",
          "airline": "FD",
          "arrivalDate": "2024-12-15"
        }
      ],
      "journey_1": [
        {
          "departureTime": "15:30",
          "flightNum": "504",
          "arrival": "HKG",
          "arrivalTime": "17:15",
          "bookingCode": "A",
          "departure": "DMK",
          "departureDate": "2024-12-30",
          "airline": "FD",
          "arrivalDate": "2024-12-30"
        }
      ]
    },
    "children": "0",
    "solutionId": "iXf1ufZoOsBU+MpHfwQD6vzfcE3X5BFe1Vxl3oa9iNn1Noc75XschKYpLVXfU17PcPI7oU/EVSKjQj2Xuxt9QoSJGTP7oW12BBtDUQvlAzaZ1z0zhjr4N5cJVh2fElsdEXXtCGI00H3Nvx98/d2z6lUfU0Yhuny0kj/rOz4IMMmghIhWyGDa4e4T7y3BrTjFwEPZh0nHoEykVO13sMp0vXt8ub60T12OXl9dooXkhpqN51MhNjyCkSYjIYff//DJ1cRBps9+3e58SI0ifR8P6FiCKSCYOmCQLFKKLU0P8+Xlv4BsqxNY0pdOKT7LeR3w2YGgt1zSCyEXZCwy/+BBLA66j01ytAzieUvdZ3sqLyc8+7IG23vo1JfqVtlJo/pvRdlQyp6gQGJDPraSkTCSvA==",
    "adults": "1",
    "ancillary": [
      1,
      2
    ]
  }
}

Notes

If you request PrecisePricing with a specific solutionId, the solution may become unavailable for various reasons. If you still want to try booking the flight, you can resend the request with solutionId set to "direct pricing". In this case, we will attempt to retrieve available seats from another booking code and fare.

The after-sales penalty returned in PrecisePricing_V6 is for reference only. Please use the Penalty API when making a reservation.

We also support calling PrecisePricing without first calling Shopping, but availability may be lower. In such cases, please set solutionId to "direct pricing".

Before calling AncillaryPricing, you must call PrecisePricing_V2 within the previous 30 minutes.

3. Create an Order

User action
Mark is now on the booking page and is entering passenger and contact details.

At this stage, you need to call PreciseBooking to create the order for the selected flight and ancillary services.

Before calling PreciseBooking, we strongly recommend calling PrecisePricing again to retrieve the latest real-time price. If the fare has changed, you can display the updated price to the customer before proceeding. If a price change occurs during PreciseBooking, the booking request will fail and an error will be returned.

Example – PreciseBooking Request

{
  "authentication": {
    "sign": "111",
    "partnerId": "111"
  },
  "booking": {
    "passengers": [
      {
        "passengerIndex": 1,
        "birthday": "1993-06-22",
        "firstName": "Mary",
        "lastName": "Jones",
        "nationality": "PH",
        "psgType": "ADT",
        "sex": "F",
        "ffpNumber": "125003559853",
        "ffpAirline": "CA",
        "ktn": "1029490",
        "redress": "2039401"
      },
      {
        "passengerIndex": 2,
        "birthday": "2021-04-12",
        "firstName": "Jason",
        "lastName": "Smith",
        "nationality": "PH",
        "psgType": "CHD",
        "sex": "M",
        "ffpNumber": "125003559853",
        "ffpAirline": "CA",
        "ktn": null,
        "redress": null
      },
      {
        "passengerIndex": 3,
        "birthday": "2023-11-24",
        "firstName": "Laura",
        "lastName": "Smith",
        "nationality": "PH",
        "psgType": "INF",
        "sex": "F",
        "associatedPassengerIndex": 1
      }
    ],
    "solution": {
      "solutionId": "OqDCC1j2GhG9XTKOd0/KF+6M/7Mn+gurPNfAlXIf00HtDIJIZmfk2/NfuNJ8U2NS4KZ5IHjxWoNYHt7SgOgt+PwbtwEji+tazJ+2u2Gmmtxr0fPZjbWUBzlNkMCRhoB3Rzt0Av7jBdhCM4LocbIrD0YzA4S6SxfrTr0woQVRPS1WLvZhJwx7IzWEctrqdnv7TOEK5QbnBDh8RalKJoykngem8SOx/0E4p6mjulWQH8XYvBwaq+THRi7ZdDLHgOLvAWpM+ja0R8Rzzu3yPfD5iNXaG1LUs87R+yDEjYQH7fY0BkctfLCoLVVZSMVyyA2UgwLRCazQwDXmYe29tsiNAg==",
      "adtFare": 117.25,
      "adtTax": 59.11,
      "chdFare": 108.87,
      "chdTax": 59.11,
      "infFare": 28.45,
      "infTax": 0,
      "journeys": {
        "journey_0": [
          {
            "airline": "FD",
            "flightNum": "503",
            "arrival": "DMK",
            "arrivalDate": "2024-12-31",
            "arrivalTime": "00:20",
            "departure": "HKG",
            "departureDate": "2024-12-30",
            "departureTime": "22:20",
            "bookingCode": "A"
          }
        ]
      }
    },
    "contact": {
      "name": "AndyGuan",
      "email": "an-dy.gu_an@pkfare.com",
      "telCode": "+86",
      "mobile": "17826050868",
      "buyerEmail": "alan.wang@pkfare.com",
      "buyerTelCode": "+86",
      "buyerMobile": "18066793072"
    },
    "ancillary": [
      {
        "ancillaries": {
          "baggage": [
            {
              "ancillaryType": 1,
              "ancillaryKey": "0c3596cc08171e66748b91bdad5c1e57",
              "payBaggageType": "1",
              "baggagePiece": "2",
              "baggageWeight": "36KG",
              "baggageCurrency": "CNY",
              "baggagePrice": "95.0",
              "description": "",
              "ancillaryJourneys": [
                {
                  "airline": "FD",
                  "flightNum": "503",
                  "arrival": "DMK",
                  "arrivalDate": "2024-12-31",
                  "arrivalTime": "00:20",
                  "departure": "HKG",
                  "departureDate": "2024-12-30",
                  "departureTime": "22:20",
                  "bookingCode": "A"
                }
              ],
              "buyerOrder": " "
            }
          ],
          "seat": [
            {
              "ancillaryKey": "4f556396a9e7490cccb75a91ae19dbca",
              "ancillaryType": "2",
              "ancillarySegment": {
                "departureTime": "00:05",
                "flightNum": "896",
                "arrival": "SGN",
                "arrivalTime": "06:20",
                "bookingCode": "I",
                "departure": "DEL",
                "departureDate": "2023-11-30",
                "airline": "VJ",
                "arrivalDate": "2023-11-30"
              }
            },
            {
              "ancillaryKey": "b9fb374c9c7fb51d88b04b415027be67",
              "ancillaryType": "2",
              "ancillarySegment": {
                "departureTime": "17:20",
                "flightNum": "632",
                "arrival": "DAD",
                "arrivalTime": "18:35",
                "bookingCode": "I",
                "departure": "SGN",
                "departureDate": "2023-11-30",
                "airline": "VJ",
                "arrivalDate": "2023-11-30"
              }
            }
          ]
        },
        "ancillaryPassenger": {
          "firstName": "Mary",
          "lastName": "Jones",
          "psgType": "ADT",
          "sex": "F"
        }
      }
    ]
  }
}

Notes

This interface depends on the results of PrecisePricing and AncillaryPricing.

Currently, we do not support booking multiple paid baggage items for the same passenger on the same flight. If more than one baggage option is submitted, only the heaviest one will be booked by default.

It is mandatory to use the PrecisePricing service before using this interface.

The entire flow should be completed within 30 minutes.

4. Pay the Order

User action
On the payment page, Mark enters his credit card details to complete payment.

At this stage, you should first call OrderPricing API to validate the order again. If the validation succeeds, you can then call Ticketing API to issue the ticket.

Example – OrderPricing Request

{
  "orderPricing": {
    "orderNum": "916798290874043301"
  },
  "authentication": {
    "sign": "111",
    "partnerId": "111"
  }
}

Example – Ticketing Request

{
  "ticketing": {
    "pnr": "TOWTAR",
    "name": "",
    "telNum": "",
    "orderNum": "916798290874043301",
    "email": "321@qq.com"
  },
  "authentication": {
    "sign": "111",
    "partnerId": "111"
  }
}

Note

You are required to provide an email address in the request. In some scenarios, such as payment failure or reimbursement caused by order status or amount verification failure, PKFARE may send notification emails to this address.

If you do not want PKFARE to send such notifications to the traveler, you may:

Set the email field to null, or

Use your company’s email address instead

5. Notify the Customer of airPNR and Ticket Numbers

User expectation
Mark waits for the airline PNR and ticket number confirmation.

At this stage, there are two ways to fulfill the customer’s needs:

Option 1 – Webhook Push

When tickets are issued, PKFARE can push the ticket number and airPNR to your webhook via the TicketIssuanceNotify API.

Option 2 – Poll Order Status

You can also query the order status through the OrderDetail API. It is recommended to poll the order status every 5 to 10 minutes. Once the order status becomes issued, you can retrieve the final ticket number and airPNR from the response.

Best Practice

We recommend using both webhook push and OrderDetail polling together to improve reliability and give you more control over the update process.

Notes

We recommend using OrderDetail at this stage because it gives you more flexibility in deciding how often to check the order status and retrieve ticket details.

The ticketingNumPush API is used to receive ticket numbers and airline PNRs. Buyer partners should provide a webhook URL based on HTTP or HTTPS. PKFARE will push the ticket number once the ticket is issued. If the request is rejected, a rejection reason will also be returned.

Difference between the two PNR fields:

PNR:

For GDS content, it is generated by the GDS

For LCC and NDC content, it is generated by PKFARE’s system as an internal booking reference

airPNR:

This is the airline reservation code that customers can use on the airline’s website

It becomes available only after ticket issuance

It may be changed by the airline during ticketing

Book air tickets with ancillaries

Flight Booking Flow Overview#

Overview#

1. Search for Flights#

Example – Shopping API Request#

Shopping Response Structure#

Notes#

2. Select a Flight and Ancillary#

2.1 Validate the Selected Flight#

Example – PrecisePricing Request#

2.2 Select Ancillary Services#

Example – AncillaryPricing Request#

Notes#

3. Create an Order#

Example – PreciseBooking Request#

Notes#

4. Pay the Order#

Example – OrderPricing Request#

Example – Ticketing Request#

Note#

5. Notify the Customer of airPNR and Ticket Numbers#

Option 1 – Webhook Push#

Option 2 – Poll Order Status#

Best Practice#

Notes#

Flight Booking Flow Overview

Overview

1. Search for Flights

Example – Shopping API Request

Shopping Response Structure

Notes

2. Select a Flight and Ancillary

2.1 Validate the Selected Flight

Example – PrecisePricing Request

2.2 Select Ancillary Services

Example – AncillaryPricing Request

Notes

3. Create an Order

Example – PreciseBooking Request

Notes

4. Pay the Order

Example – OrderPricing Request

Example – Ticketing Request

Note

5. Notify the Customer of airPNR and Ticket Numbers

Option 1 – Webhook Push

Option 2 – Poll Order Status

Best Practice

Notes