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.idhas valueENT:FulfilmentMethod:Bifrost. Use this to identify third-party order lines.orderLines[].salesPackageRefhas valueENT:SalesPackage:ThirdPartyProductorderLines[].fareProductsis 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
- 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:
- Find the traveller IDs on the third-party order line:
orderLines[].travellers[].travellerId. - 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.