Making an interline purchase

For this guide, we will refer to the main Provider as "Provider A", and the associated Seller for that provider as "Provider B". You will use the x-api-key for "Provider A" for the whole purchase process.

In order for these two providers to be considered as Interline "partners", they need to have a bi-directional relationship between them. So "Provider A" must be a seller for "Provider B" and vice-versa.

If a product from "Provider A" is added first, it is considered to be the main provider. If items are deleted, the cart's main provider will be the account of the first item left after deletion.

When posting a payment only the payment types of the main provider can be used. For vouchers and gift certificates, only those of the main provider can be used for paying the portion of the price associated to that main provider.

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

Prerequisites

You will need an X-API-KEY and a username and password to authenticate.

Steps to complete a purchase

1) Select a product

Get the list of configured products, select one, and remember its _id. 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) Get fares

Get available fares for the product that you have selected, using your product's _id as a filter parameter.

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) Find and select available 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 . Select only one Fare Class from the trip search results, and remember it's id. The id will need to be specified when adding the item to the shopping cart.

At this time, if you are searching for a round-trip, the Fare Class that is selected for the passenger's Outbound and Return Trip must be the same.

6) Add an item to the cart

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.

7) Repeat steps 1-6, but use a product from Provider B

Items added for "Provider B" will need to include that provider's id.

To see the API calls in action, you can look at the Postman collection at the bottom of this document.

8) Retrieve payment types

To complete the order, first retrieve the available payment types and select one. Remember, these must be the payment types for the main provider, "Provider A" in our example.

9) Get country and province information

Get our list of country and province information, and remember the result. You will need a valid Country Code and Province when paying for the order, in the next step.

10) Complete the order

Create an order (pay for the items in the cart) using one of the available payment types.

Once the payment is accepted, the booking is complete.

11) Download tickets

In some cases you may want to download tickets for the booking. The tickets are downloaded as PDF files.

12) 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 two one way trip reservations as a customer, with each product being from a different provider. In order to use it successfully, you will need your x-api-key, and valid stations and routes set up. In this example, we create a customer, but you can use an existing customer if you prefer.

After importing the collection, and the environment, make sure your collection is using the new environment, and that you have set the values. Variables that start with "YOUR_" will need to be replaced with a value specific to your situation. 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