Exchange Ticket

Exchange (change) tickets for an existing booking. This is a 3-step process: Search → Reprice → Confirm.

---

Step 1: Exchange Search

Search for available flights to exchange tickets.

Endpoint

• URL: /api/v1/flight/exchange-search
• Method: POST
• Auth Required: Yes (Bearer Token/X-api-key)
• Content-Type: application/json

Request Structure

Field	Type	Required	Description
system	string	Yes	Booking system code (e.g., VN, VJ, 1A)
bookingCode	string	Yes	Booking code (PNR)
promoCode	string	No	Promotional discount/coupon code
flightValueCancels	array	Yes	Flight values to cancel (from booking)
newFlights	array	Yes	New flight requests (see FlightRequest)

FlightRequest Object

Field	Type	Required	Description
leg	integer	No	Flight segment sequence number
startPoint	string	Yes	Departure airport code (3-letter IATA)
endPoint	string	Yes	Arrival airport code (3-letter IATA)
departDate	DateOnly	Yes	Departure date (YYYY-MM-DD format)
preferCabin	string	No	Cabin class: Y - Economy, F - First, C - Business, W - Premium Economy, M - Non-premium Economy

Sample Request:

{
  "system": "VN",
  "bookingCode": "ABC123",
  "promoCode": "DISCOUNT10",
  "flightValueCancels": ["encoded_flight_value_1"],
  "newFlights": [
    {
      "leg": 0,
      "startPoint": "SGN",
      "endPoint": "HAN",
      "departDate": "2024-06-02",
      "preferCabin": "Y"
    }
  ]
}

Response Structure

Returns an array of TripOtaFlightSearchResponse objects (same as Search Flight).

Field	Type	Nullable	Description
system	string	Yes	System name (e.g., VN, VJ, 1A)
status	boolean	No	true if successful, false if failed
error	object	Yes	Error details (if any)
description	string	Yes	Error description (if any)
trackingId	string	Yes	Tracking ID for request logs
trackingTime	string	Yes	Time for request tracking (ISO 8601 format)
fareDatas	array	Yes	List of available exchange flight options

Sample Response

[
  {
    "system": "VN",
    "status": true,
    "error": null,
    "description": null,
    "trackingId": "exchange-search-001",
    "trackingTime": "2025-07-01T07:00:00.000Z",
    "fareDatas": [
      {
        "airline": "VN",
        "startPoint": "SGN",
        "endPoint": "HAN",
        "departDate": "2024-06-02",
        "flightValue": "encoded_new_flight_value_from_exchange_search",
        "totalFare": 2450000,
        "currency": "VND"
      }
    ]
  }
]

---

Step 2: Exchange Reprice

Check the price difference before confirming the exchange.

Endpoint

• URL: /api/v1/flight/exchange-reprice
• Method: POST
• Auth Required: Yes (Bearer Token/X-api-key)
• Content-Type: application/json

Request Structure

Field	Type	Required	Description
system	string	Yes	Booking system code
bookingCode	string	Yes	Booking code (PNR)
flightCancels	array	Yes	Flight values to cancel
flightExchanges	array	Yes	Flight values to exchange (from exchange-search)

Sample Request:

{
  "system": "VN",
  "bookingCode": "ABC123",
  "flightCancels": ["encoded_flight_value_1"],
  "flightExchanges": ["encoded_new_flight_value"]
}

Response Structure

Field	Type	Nullable	Description
system	string	Yes	System name
status	boolean	No	Success status
error	object	Yes	Error details
description	string	Yes	Error description
trackingId	string	Yes	Tracking ID
trackingTime	string	Yes	Tracking time
bookingCode	string	Yes	Booking code
exchangeValue	string	Yes	Exchange value for confirm step
exchangePricingDetails	array	Yes	Pricing details (see ExchangeTicketInfo)

Sample Response

{
  "system": "VN",
  "status": true,
  "error": null,
  "description": null,
  "trackingId": "exchange-reprice-001",
  "trackingTime": "2025-07-01T07:05:00.000Z",
  "bookingCode": "ABC123",
  "exchangeValue": "encoded_exchange_value_from_reprice",
  "exchangePricingDetails": [
    {
      "ticketNumber": "2389876543210",
      "passenger": "NGUYEN VAN A",
      "oldPrice": { "amount": 2000000, "currency": "VND" },
      "newPrice": { "amount": 2450000, "currency": "VND" },
      "different": { "amount": 450000, "currency": "VND" },
      "penalty": { "amount": 100000, "currency": "VND" },
      "refund": { "amount": 0, "currency": "VND" }
    }
  ]
}

---

Step 3: Exchange Confirm

Confirm and finalize the ticket exchange.

Endpoint

• URL: /api/v1/flight/exchange-confirm
• Method: POST
• Auth Required: Yes (Bearer Token/X-api-key)
• Content-Type: application/json

Request Structure

Field	Type	Required	Description
system	string	Yes	Booking system code
bookingCode	string	Yes	Booking code (PNR)
exchangeValue	string	Yes	Exchange value from reprice step

Sample Request:

{
  "system": "VN",
  "bookingCode": "ABC123",
  "exchangeValue": "encoded_exchange_value_from_reprice"
}

Response Structure

Field	Type	Nullable	Description
system	string	Yes	System name
status	boolean	No	Success status
error	object	Yes	Error details
description	string	Yes	Error description
trackingId	string	Yes	Tracking ID
trackingTime	string	Yes	Tracking time
bookingCode	string	Yes	Updated booking code
exchangePricingDetails	array	Yes	Exchange pricing details (see ExchangeTicketInfo)

ExchangeTicketInfo Object

Field	Type	Nullable	Description
ticketNumber	string	Yes	Ticket number
passenger	string	Yes	Passenger information
oldPrice	Money	Yes	Old ticket price
newPrice	Money	Yes	New ticket price
different	Money	Yes	Price difference
penalty	Money	Yes	Penalty amount
refund	Money	Yes	Refund amount

Sample Response:

{
  "system": "VN",
  "status": true,
  "error": null,
  "description": null,
  "trackingId": "abc123",
  "trackingTime": "2025-07-01T07:00:00.000Z",
  "bookingCode": "ABC123",
  "exchangePricingDetails": [
    {
      "ticketNumber": "2389876543210",
      "passenger": "NGUYEN VAN A",
      "oldPrice": { "amount": 2000000, "currency": "VND" },
      "newPrice": { "amount": 2050000, "currency": "VND" },
      "different": { "amount": 50000, "currency": "VND" },
      "penalty": { "amount": 100000, "currency": "VND" },
      "refund": { "amount": 0, "currency": "VND" }
    }
  ]
}

---

Error Codes

This endpoint may return the following error codes:

• 17000 - Exchange Ticket: Errors specific to ticket exchange operations (17000-17004)
• 00000 - Flight Hub (General Errors): General system and authentication errors (00001-00056)

For a complete list of error codes, see Error Codes.

---

Security & Validation

• All input is validated for type and required fields.
• Only authenticated users can access this endpoint.
• The endpoint is protected against tampering with bookingCode and segment data.

---

Validation Questions

• Are there limits on the number of exchanges per booking?
• Are there time or fare restrictions for exchanges?

---

For integration support, see Contact Support.