Entur Developer
Guides

How to purchase third-party tickets

Entur sells tickets on behalf of third-party partners, such as commercial express buses in Norway and train journeys in Sweden. This guide shows how to purchase these tickets if you already have an integration with the Entur Sales Platform.

The flow is mostly the same as for Entur tickets. You use the same APIs, with some extra steps and restrictions.

Before you begin

To use this guide, you need to:

  • Have a client with the permissions needed for the sales platform.
  • Have your and enabled for third-party sales.

This guide assumes you are familiar with the sales platform.

1. Search for and reserve offers

Find trip patterns with Journey Planner. A trip can contain both Entur and third-party legs. Use the trip pattern as input when searching. Third-party offers have availableFulfillmentMethods: ENT:FulfilmentMethod:Bifrost.

Reserve offers as before, but use the recommendations in the response to pick offers. Do not combine offers yourself.

Note the following:

  • Search for offers with the actual number of travellers. You cannot reuse an offer for another traveller.
  • Seat selection is not supported, but some partners assign seats automatically.

2. Display order information

An order line representing a third-party ticket has the following traits:

  • orderLines[].distributionDetails.fulfillmentMethodRef.id has value ENT:FulfilmentMethod:Bifrost. Use this to identify third-party order lines.
  • orderLines[].salesPackageRef has value ENT:SalesPackage:ThirdPartyProduct
  • orderLines[].fareProducts is empty

Third-party products are not available in Products, look them up with the Third Party Product API.

Fetch all third-party products for the order:

or by order line:

To find which partner an order line belongs to, inspect orderLines[].travelSpecification.legs[].authorityRef.id or thirdPartyProducts[].authorityId on the corresponding third-party product.

3. Update personal details

What we need

Third-party partners require names and contact details for all travellers in the offer search. Collect:

  • First name
  • Last name
  • Email
  • Phone number

Provide these details for every traveller. The exception is NOR-WAY (NWY:Authority:d1ea7af1-3c2a-4825-893f-21408ef08480), which only needs details for one traveller, unless the trip involves several third-party partners.

For groups, you can collect one email and phone number and use them for all travellers. For a round trip, you can use the same traveller for both journeys, so you only submit the details once.

How to provide it

We create a temporary customer for each traveller in the offer search. Retrieve these customers and update them with the travellers' details.

To get the customer references:

  1. Find the traveller IDs on the third-party order line: orderLines[].travellers[].travellerId.
  2. Match them with travellers[] to get the customerNumber: travellers[].ref.id.

Retrieve the customers:

The customer does not have an age field, but if you submitted an age in the offer search, we set the dateOfBirth field to yesterday's date minus the submitted age.

Update the customers with:

4. Handle payments

Handle payments as before. However, we fulfil third-party order lines after payment is completed, and the order is not confirmed until all of them succeed. This can cause a delay between payment and confirmation. After payment, poll the order status. If any partner fails to confirm, the order will still get status=CONFIRM, but also the field: failed=true, and the order will be refunded automatically.

5. Handle tickets

Handle tickets as before, but only PDF tickets are supported.

6. Handle refunds

Handle refunds as before, but note that:

  • Refund rules vary between partners, and Products has no rules you can rely on. Your client must send a refund request and handle the response, since the partner decides whether to accept it.
  • You can only refund the entire order.
Last modified on
Did you find what you were looking for?