Rail bookings cannot be canceled because they are ticketed immediately after booking. Therefore, rail bookings must be refunded or exchanged. To exchange a rail booking:
-
Quote the exchange using RailExchangeQuoteReq.
-
Process the exchange using RailExchangeReq.
Quote Request
Minimum Data
LocatorCode provides the unique identifier for the rail reservation.
SearchRailLeg contains the time and location data for one or more legs to be searched. The minimum required data for a Rail Search request are:
-
Origin location. Origin and destination data must be supplied in normalized form for Universal API. Reference Data can be used to obtain the normalized form if required. Include RailLocation in SearchOrigin or SearchDestination to search for a specific train station.
-
Destination location (supplied in the same format as the origin location).
-
Type of journey (one-way or round-trip).
-
Departure date/time of outbound journey.
-
Departure date/time of inbound journey (if applicable).
-
Number of passengers (defaults to one adult passenger). See Rail Availability with Passenger Type for information about different passenger types.
For the SearchOrigin and SearchDestination elements:
-
IATA Codes can be sent in the Airport, City, and CityOrAirport attributes.
-
UCodes can be sent in the RailLocation attribute.
A Rail Exchange request can be sent with the following data to request fares for specified train segments:
- ResponseType="Fares"
- Journey Token (from the previous Rail Exchange response)
- Host Token (from the previous Rail Exchange response)
This functionality is provided for rail distributors that recommend a second Rail Availability or Exchange Quote request to confirm fares as part of their business processes. Currently, these distributors include Amtrak.
Optional Data
Discount Card
The @DiscountCard in RailExchangeQuoteReq/SearchPassenger/ provides the ability to apply multiple discount codes per passenger for rail reservations.
- Multiple @DiscountCards per passenger can be applied for Low Fare Shop, Rail Availability, Rail Exchange Quote, Rail Exchange, and Rail Booking.
-
The response returns in RailExchangeQuoteRsp/RailExchangeSolution/RailPricingInfo/PassengerType/DiscountCard
- Although this functionality is not vendor specific, only SNCF and BeNe currently support multiple discounts per passenger.
Quote Response
RailExchangeSolution contains information about the rail booking and exchange.
If a FareClass is not returned in the response, CabinClass="Economy" is returned. In earlier schemas, CabinClass= "Standard" is returned.
Universal API compares the corporate DiscountCode values in a RailAvailabiltySearchReq with the DiscountCode values returned in RCS:
- With Rail v35.0 and later, this logic is replicated in additional services to return the DiscountCode values at the passenger level in the Rail Create Reservation Response, Rail Exchange Quote Response, and Rail Exchange Response.
- The /DiscountCard @Code @Description @Number is mapped in the RailExchangeQuoteRsp/RailExchangeSolution/RailPricingInfo/PassengerType path.
Errors and Warnings
If Universal API does not recognize TrainTypeCode(the train service type), a value of "UNKNOWN is returned for the description in the TrainType attribute.
Exchange Request
RailExchangeReq/Rsp was in the Universal schema in v34.0 and earlier. With Rail v35.0 and later, RailExchangeReq/Rsp is in the Rail schema.
At least one IATA or UCode must be sent in the exchange request in the attributes: Origin, Destination, RailLocOrigin, or RailLocDestination in the RailExchangeSolution/RailJourney, RailJourney/RailSegment, or RailPricingInfo/RailFare elements or an error is returned in the response and the request fails.
A mandatory Booking Action Type attribute must be added to Rail Exchange requests. This attribute allows the same @BookingActionType values that are available in the Rail Booking except "Ticket". If RailExchangeReq omits @BookingActionType, the request fails and an error is returned. There is no change to the Rail Exchange response. Enumerated values are:
- Initiate (used for a provisional booking)
- Final (used to book with no ticket issuance)
- FinalTicket (used to book and issue the ticket)
Note: The Universal Record History captures changes to:
-
RailLocOrigin and RailLocDestination in RailJourney, RailFare, and RailSegment.
-
Customer loyalty information.
-
Corporate Discounts or Promotion Codes:
-
Multiple Discount Codes can be sent in the request, and a request can include both discounted and non-discounted passengers.
- You can apply multiple discount codes per passenger for rail reservations. Release 17.3
- Although this functionality is not vendor specific, only SNCF and BeNe support multiple discounts per passenger as of July 3, 2017.
- Multiple @DiscountCards per passenger can be applied for Low Fare Shop, Rail Availability, Rail Exchange Quote, Rail Exchange, and Rail Booking.
Exchange Response
Fare Class, Cabin Class, Class Code
If a FareClass is not returned in the response, CabinClass="Economy" is returned. In earlier schemas, CabinClass= "Standard" is returned.
With Universal v34.0 and earlier, most rail suppliers used a combination of the class code (same as booking code) and the cabin class to determine rules of the fare, as typically there are no fare rules data available through the provider APIs:
- The class code and cabin class are needed in the request so that the correct fare rule text can be provided for each segment of the journey. If provided, the data was returned only in the Rail Segment attribute of the Rail Availability Response and Rail Exchange Quote Responses.
- With Rail 35.0 and Universal v35.0, because the class code and cabin class can differ for each train segment, @ClassCode and @CabinClass are returned in the Rail Create Reservation Response, Universal Record Retrieve Response, and Rail Exchange Response.
/UniversalRecord/RailReservation/RailJourney/RailSegment @ClassCode and @CabinClass
Universal API compares the corporate DiscountCode values in a RailAvailabiltySearchReq with the DiscountCode values returned in RCS:
- With Rail v35.0 and later, this logic is replicated in additional services to return the DiscountCode values at the passenger level in the Rail Create Reservation Response, Rail Exchange Quote Response, and Rail Exchange Response.
- The /DiscountCard @Code @Description @Number is mapped in the RailExchangeRsp/UniversalRecord/BookingTraveler path.
Canceled segments are removed from the UR and all changed/cancelled segments are recorded to the UR History.
Errors and Warnings
If Universal API does not recognize TrainTypeCode(the train service type), a value of "UNKNOWN is returned for the description in the TrainType attribute.
If "Business" is returned in the CabinClass attribute of RailFare or RailAvailInfo, it is ignored and a warning is returned.
Exceptions
BeNe (BN)
Exchanges for BeNe bookings are supported through Universal API with Rail.xsd. See the associated topic for more details.
Amtrak (2V)
E-Vouchers
@RetainAmount value is used for E-Voucher, which are supported only for Amtrak (2V) in RailExchangeQuoteRsp/RailExchangeSolution/
RailExchangeInfo.
- Attributes in the Rail Exchange Quote Response may contain the Refund and/or eVoucher (Retain) information.
- Refund or Retain data from the Rail Exchange Quote response must be included in the subsequent Rail Exchange request (RailExchangeReq @RefundOption)
- In the Rail Exchange request, @RefundOption indicates if the traveler wants and price reduction from the exchange to be applied as a refund to the original form of payment or to retain the price difference in an eVoucher (Amtrak only. If the exchange is for Amtrak and if @RefundOption is not set, the request is populated to Amtrak with "Refund.").
E-Voucher can be redeemed only at Amtrak.com, an Amtrak ticket office, or by phone at 1-800-USA-RAIL. Details are available at http://www.amtrak.com/evouchers-your-travel-credits-stored-electronically.
There are no changes to the RailExchangeRsp. A subsequent UR Retrieve request can be used to verify the application of the refund/retain values, a UniversalRetrieveRsp will include the information in a remark.
Form of Payment
Amtrak requires that the credit card used in a RailExchangeReq be the same as the credit card used in the original booking:
- If the credit card sent for the exchange is different than the original, Amtrak will override it and use the original.
- If the credit card is expired, the exchange transaction will fail and the customer must contact Amtrak directly for any changes.
Modify
Previously, Universal API did not support the ability to modify Amtrak bookings.
The following booking data can be modified using Rail Exchange Quote:
- Train number
- Travel date
- Class of service
RailExchangeQuoteReq/RailSegmentList/RailSegment @TrainNumber @DepartureTime @ArrivalTime @CabinClass
To Modify:
- Send the RailExchangeQuoteReq to check the availability for same Origination / Destination with the change of Date or time. The RailExchangeQuoteRsp returns with the associated information.
- Send a second RailExchangeQuoteReq that includes the selected train segments, dates and class of service (even if train numbers/segments are not a change to the original booking). RailExchangeQuoteRsp returns with the updated data.
- Send a RailExchangeReq including the selected journey/fare and any other necessary information, such as FOP if add-collect is required (2V always requires FOP and it must be the same as used in the original booking). The RailExchangeRsp returns the successful or unsuccessful modification of the booking. If successful, the response will include information regarding any refund, refund fee and/or add-collect.
Note: Amtrak does not allow changes to passenger information. If a Rail Exchange Quote request for Amtrak includes passenger information, it is ignored and a warning is returned: Passenger Modification is not supported by distributor. Passenger list is ignored.
