Making a reservation purchase with dynamic form 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
Retrieve the list of configured products, select a product that is already associated to a dynamic form of type "passenger" and take note of both the product's _id and the dynamic form's _id.
{
"dynamicForms": [
{
"_id": "64821a01b467650661164b45",
"type": "passenger"
}
],
}
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.
If you have configured Fare Classes for your passengers, you must select a product with pricingType = "journey" to make use of Fare Classes in the following steps.
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) Select an origin station
Get all possible origin stations for your selected product.
Select an origin station, and remember its _id.
4) Select a destination station
After selecting an 'origin' station, get all possible destination stations that can be reached from that starting point.
This endpoint does not guarantee that there are schedules available between the origin and destination stations - this can only be determined by performing a Trip Search.
Select a destination station, and remember its _id - this will be needed when searching for Trips.
5) Select trips
Find trips that are available for your selected product, fares, origin, destination, and travel date(s).
From the results, select a single departure trip. If searching for a round-trip, also select a return trip. Remember each trip id, a long hash that will look something like this:
{
"id": "eyJhY2NvdW50SWQiOiI1OTEwY2ZiYWZhMWI5MDRkMGMwMDAwMTUiLCJwcm9kdWN0SWQiOiI1OTEwY2ZiYWZhMWI5MDRkMGMwMDAwMTYiLCJvcmlnaW5JZCI6IjU5MjQ1OTBlOTk4MmNmMjA3YzBkZjQwMCIsImRlc3RpbmF0aW9uSWQiOiI1OTI0NTkyODk5ODJjZjIwN2MwZGY0MDEiLCJmYXJlSWRzIjoiNTkyNDViNTc5OTgyY2YyMDdjMGRmNDAyOjEiLCJkZXBhcnR1cmVEYXRlIjoiMjAxNy0xMC0yOCIsImRlcGFydHVyZVRpbWUiOiIwOTowMCIsImNoYW5uZWwiOiJ3ZWJzYWxlcyIsInNlZ21lbnRzIjpbeyJyb3V0ZUlkIjoiNTkyNDU5NDE1MDJjYzcxMDcyMDAwMDFlIiwic2NoZWR1bGVJZCI6IjU0MGZkNWQ5LThiZDEtNGIxNS05ZDZlLTJiNzk3ZmFhYWM1NyIsIm9yaWdpbiI6IkJlcmxpbiBDZW50cmFsIGJ1cyBzdGF0aW9uIChaT0IpIiwiZGVzdGluYXRpb24iOiJXYXJzYXcgV2VzdCBidXMgc3RhdGlvbiJ9XSwidGlja2V0VHlwZSI6Im9uZXdheSJ9"
}
If Fare Classes are being used, you will need to select the passenger's desired Fare Class for their outbound and return trip. Select one Fare Class from the departure trip, and remember it's id. If you searched for a round trip, also select a Fare Class from the return trip, and remember its id. These Fare Class ids will need to be specified when adding the item to the shopping cart.
(You can learn more about working with fare classes here).
6) Authenticate
You are almost ready to add the trip 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.
7) Working with dynamic form
Using a dynamic form, retrieve the dynamic form with the dynamicFormId from the selected product.
When working with dynamic forms, you'll be dealing with custom fields that correspond to the standard fields used in the sales flow. If you're using the people lookup APIs, this mapping between custom and standard fields is established.
To view this mapping, refer to the mappedStandardBtrzFields property in the dynamic form record. This will give you a clear understanding of how the custom fields align with Betterez's standard fields necessary for completing a purchase.
8) Working with people lookup
If your dynamicForm has peopleLookup enabled you will need to get the peopleLookupId for each passenger.
In case you are working with parcels yoy will need to get the peopleLookupId for sender and receiver.
9) Add an item with people lookup and dynamic form to the cart
For this step you will need the peopleLookupId for each person and the dynamicFormId you got from the product.
In the reservation object you will add the dynamicFormId and in the passengers array for each passenger you will add the peopleLookupId that is returned with each post done above.
In the parcel object you will add the peopleLookupId in the extra/from and extra/to property
Add the selected trip to the shopping cart.
Remember the cartId and the total from the response. You will need this information to complete the order:
(At this point you may want to apply a promo).
10) Select a payment type
To complete the order, first retrieve the available payment types and select one. Remember the method field.
11) 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.
12) 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.
13) (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 reservation using the dynamic form, 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 set the {{basePath}} environment variable to https://sandbox-api.betterez.com.