Making a purchase of a ticket with a flexpass

Purchasing a ticket with a flexpass (a.k.a. redeeming) involves several steps.

Although it is a single call to an API, you may need to add additional data for the redemption, depending on the flexpass. Also, you may want to make an early validation of that flexpass, to give early feedback to the user that the redemption cannot proceed.

In order to redeem a flexpass you will need to provide the following additional information:

  • flexpass id
  • departure date
  • trip the user want to travel in
  • passenger data (if needed)
  • origin and destination (if needed)

Please make sure you read the Conventions before continuing with this guide.

Prerequisites

You will need an X-API-KEY and a Basic Access Authentication token generated from your username and password.

1) Authenticate

First, you must authenticate.

Store the shortToken from the authentication response, so that you can use it in subsequent API calls.

2) Get flexpass

You will need the flexpass id to be used to purchase the ticket. Using that id, the first step is to fetch the flexpass data for purchasing the ticket (redeem).

You have to use the GET /flexpasses/id API to retrieve the flexpass providing its id. You can check the Postman collection for an example on how to retrieve a flexpass

3) Determine validity of flexpass

You can check if a flexpass is in condition to be redeemed. This is usually handy to give earlier feedback to the user about a flexpass that is expired, or used up or any other condition that may render it unredeemable.

Check how to use this functionality in the validate flexpass endpoint documentation In addition to the flexpass id, you also have to provide the timezone. Check the tz database names.

4) Determine additional data

Depending on the configuration of the flexpass, additional data may be needed to purchase/redeem it.

  • Departure date (of the reservation, normally chosen by the customer).
  • Fare used. Save the fareId from the flexpass (step 1).
  • Reservation product. Save the id found in flexPassOptions->reservationProductId from the flexpass (step 1).

Origin and Destination

  • If the flexpass is Point-to-point (flexPassOptions->networkWide is false) both stations will be present on the flexpass (step 1). Save the ids (fromId and toId) and the names (from and to).
  • If the flexpass is Network-wide (flexPassOptions->networkWide is true) you will need to get them from the customer. See the get stations guide to understand how to use the /inventory/stations API. Note that the productId parameter you have to provide is the Reservation product retrieved earlier (flexPassOptions->reservationProductId) and NOT the flexpass product id nor the flexpass id. Save the ids and the names of both stations.

Passenger data:

  • If restricted is false (flexPassOptions->restrictPassenger) the passenger is not restricted to be the customer of the flexpass. In that case, you want to collect the new passenger information (firstName, lastName and email).
  • If restricted is true, save the firstName, lastName and email present in the flexpass obtained in step 1.
  • Whether it is restricted or not, you may want to provide comments for this redemption.

In the accompanying Postman collection there are several examples to perform these retrievals.

5) Retrieve further data from additional APIs

Here we describe which endpoint you need to access in order to retrieve additional pieces of information needed for the redemption (step 5).

Trips:

You will need Departure date (yyyy-mm-dd), fareId, reservationProductId, ids from Origin and Destination (see step 3). These data will be used to obtain a list of trips from the trips API. Make the customer choose one of them, and save the following from the FIRST AND ONLY segment (trips->departures->segments) (flexpass redemption does not support trips with connections):

  • routeId
  • scheduleTime (we will refer to it as tripTime)
  • name (we will refer to it as scheduleName)
  • scheduleDisplayName

Fare:

You must obtain a fare data structure and save it for the final step.

Checkout the /inventory/fare API to see how to retrieve a fare with the fareId you saved in step 3. Save the full data structure under the fare key.

6) Make ticket purchase (redeem flexpass)

In this step we will interact heavily with the redemptions API. Check the redemptions API to see more details on how to use it, responses and errors.

For redeeming the flexpass you will need to provide:

  • itemCode (Prepend "FP-" to the flexpass id from step 1. Example: FP-5d55712cd44ebe9a2df264b3)

options

options.selectedTrip (obtained in step 4)

  • options.selectedTrip.date
  • options.selectedTrip.routeId
  • options.selectedTrip.time
  • options.selectedTrip.scheduleName
  • options.selectedTrip.scheduleDisplayName
  • options.productId (Reservation product from step 3)
  • options.selectedStation.id (Origin station id, from step 3)
  • options.selectedStation.name (Origin station name, from step 3)
  • options.tripStations (an array containing two elements with id and name. The first from the origin and the second from the destination, from step 3). Note that the first element, the origin station, has the same data as the selectedStation above.
  • options.shouldMarkReservationAsUsed: false

options.passenger Passenger data obtained in the previous steps

  • options.passenger.firstName (step 3)
  • options.passenger.lastName (step 3)
  • options.passenger.email (step 3)
  • options.passenger.comments (step 3)
  • options.passenger.fare (the full data structure saved in step 4)
  • options.passenger.fareId (step 3)
  • options.passenger.seats: [] (seat selection is not supported yet)

Check the postman collection to see an example of the data structure you must provide. Note that part of this structure (redemptions) is an object with various empty arrays.

After submitting this information the redemption is complete and a ticket will be generated. Save the transactionIds if you need to perform further actions. Note that in this case this array returns only one transactionId.

For downloading tickets you will need the transactionId saved before. Refer to download tickets

Postman resources

If you would like to use Postman to test the API, we have included a collection you can use as a starting point below.

This collection is designed to allow you to redeem a flexpass, by following the steps above.
In order to use it successfully, you will need your X-API-KEY and data (like stations, routes, payment types and so on) set up for your account.

After importing the collection, and the environment, make sure your collection is using the new environment, and that you have set the initial values. On each step, you should manually add the missing environmental values with the values you get from the previous steps.

If you are going to be using our API in sandbox, please change the {{basePath}} environment variable to https://sandbox-api.betterez.com.

Postman Collection

Postman Environment