The need initiating this Best Practise was found in the "Movingo" collaboration.

Purpose

In order for a transport authority to enable refresh of its travellers’ tickets sold in a 3rd part sales channel, a ticket refresh procedure is needed in different cases.
The procedure, implemented in the 3rd parts' sales channel, should be started on a schedule and include all current valid tickets.
Without the procedure, in combination with cacheing of tickets in the sales channel and/or in the ticket bearer, it is not possible to update the format/validity of the tickets during the tickets’ validity period.

Implementation reference

Movingo

Use Cases

1. Subticket regular refresh - purchased tickets

If the conditions/validity and/or of technical/functional reasons Transport authorities wants to add informnation to already purchased subtickets this procedure needs to be added.

Subticket regular refresh is done for subtickets that have been successfully purchased and where the parent ticket is still valid.

Default refresh interval: 7 days - from last update timestamp
- Configurable refresh interval (from last update timestamp) for all subtickets/participants in a main MTB
- Refresh process during night
Monitoring is set up to alert administrators if more than 10 refresh attempts fail during a single nightly process from one participant.
TicketAPI endpoint: GET/ticket/{ticketId} request is used to the BOB participant who originally issued the ticket.
- The new MTB container is saved to the subticket entity and the MTB container of the main ticket is also updated with the new subticket MTB information.

2. Subticket purchase failure

A subticket resale process is started if one subticket purchase fails during the sale of a main ticket (main-MTB).

Information about the failed initial sale request of subticket is recorded.
- Monitoring is set up so, that customer support and admin are notified as soon as first regular resale attempt fails.
1st subticket sales retry: 1 minute after initial sale
- Start time for resale attempt is from initial failed sale timestamp of subticket
If 1st sales retry fails - new sales retry hourly up to 24 times
- Parameters are configurable
- If resale still fails after maximum number of retries - manual process in contact with concerned participant required.
Successful resale of subticket updates main MTB ticket
Check for unissued subticket using TicketAPI endpoint: GET/ticket?requestID=
- If issued: reuse issued TicketID from Transport Authority to connect to MTB-subticket.
API enpoints used:
- POST /product
- POST /manifest
- POST /ticket

The logic for subticket resale is as follows:

If POST /ticket request failed, GET /ticket with {requestId} filter is made to check, if the ticket has not been issued and the error was with receiving the response. If ticket is returned, the process is completed.
If GET /ticket request did not provide a response, but the Manifest at mtb_ticket_in.manifest is still valid - new POST /ticket request is made with the same Manifest
If the Manifest is not available or has expired, a new POST /product request is made to start a new sales process with startOfValidity from the Movingo parent ticket

If POST /product was successful, make POST /manifest and POST/ ticket queries with the received product_id

In case of a successful sale on the retry attempt, the subticket MTB are added to the Movingo ticket parent ticket MTB container and is available for the customer applications.

3. New participant - addition to main MTB (ex. Movingo)

When a new participant finishes its BoB-implementation and is ready including its subtickets within a ticket collaboration (ex. Movingo - region period tickets) a resale/recreation of the main MTB and creation of the new participants sub-MTB is made.

API endpoints used:

POST /product
POST /manifest
POST /ticket

The process for adding a new participant is as follows:

Import participant metadata and url-s from Samtrafiken (done automatically)
Update the relations of the zone combinations where new participants tickets should be sold to use the added participant info
For each Movingo ticket that has a fare rule with the new participant, a new subticket sale must be initiated with following information:

fare / product / traveler categories - categories of the Movingo parent ticket product
startOfValidity - starting time of the Movingo parent ticket
If needed by the participant - stopId for origin and destination for point to point tickets

Browser not supported