Purchasing a flexpass involves several steps.
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.
Steps to complete a purchase
1) Select a product
Get the list of configured products, select one with family = flexpass
, and remember its _id
and flexPassOptions
.
The product that you select will determine which Fares (and Fare Classes, if in use) are available when performing a Trip Search and making a purchase.
Note that depending on the value of certain properties of the product you will need to provide further information when adding the item to the cart:
restricted passenger (flexPassOptions->restrictPassenger)
- if
true
provide passenger data intopassengers
array of product.
duration type (flexPassOptions->durationType)
- if
monthly
provide month and year inyearMonth
property of product. - if
days
provide start date instartDate
property of product.
pricing (pricingType)
- if
point-to-point
provide origin and destination infrom
andto
properties of the product.
2) Select fares
Get available fares for the product that you have selected, using your product's _id
as a filter parameter.
Take note of the ids of the fares you need for the purchase.
3) (Point to point flexpass) Select origin and destination
If the pricing of the flexpass was point-to-point
, you should collect the origin and destination stations.
If the pricing of the flexpass was network-wide
, you don't need to provide additional data.
Get all possible origin stations for your selected product.
Select an origin station, and remember its _id
.
After selecting an 'origin' station, get all possible destination stations that can be reached from that starting point.
Select a destination station, and remember its _id
.
The specific trip will be selected at the moment of redemption.
4) Authenticate
You are almost ready to add the flexpass into the shopping cart. First, you must authenticate.
Store the shortToken
from the authentication response, so that you can use it in subsequent API calls.
5) Add a flexpass to the cart
Add the item to the shopping cart.
Depending on the flexpass product configuration, you'll need to provide specific data as part of the flexpass item definition. Please refer to step 1 for details.
Additionally, remember to send the flexPassOptions
(saved on step 1) as part of the item definition. Also, please check the item key should be flexpass
instead of reservation
.
Remember the cartId
and the total
from the response. You will need this information to complete the order.
6) Select a payment type
To complete the order, first retrieve the available payment types and select one. Remember the method
field.
7) Select country and province info for the customer
Get our list of country and province information, and remember the result.
You will need a valid ISO
code of a country and a province (if it applies) to complete the customer information when paying for the order, in the next step.
8) Create the order
Create an order (pay for the items in the cart) using the information from the previous steps.
Once the payment is accepted, the booking is complete. Take note of the transactionIds
if you need to perform further actions, like downloading the tickets.
9) (Optional) Download tickets
In some cases you may want to download tickets for the booking. The tickets are downloaded as PDF files.
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 purchase 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
.