This product feature is about to be discontinued. For information about the current ticketing, see the provider feature tickets.

Ticketing

The product feature ticketing allows purchasing public transport tickets for rides.

When this feature is active and a ticketing adapter is configured, ioki Platform can offer, issue, retrieve, and cancel public transport tickets for rides.

Activate this feature

Roles: Super Admin

1. Navigate to the management settings of the product.
2. Within the Product features section, select the checkbox Ticketing.
3. Select Save.

Configure this feature

This feature can be configured within the section Ticketing in the management settings of a product.

The admin procedure for this feature, including viewing and canceling tickets in Control Center, is documented in Ticketing in Control Center.

Note that tickets can be issued only from station to station, because DHIDs are required. If tickets are needed for hybrid or address-based matchings, ioki Platform finds a reference station for the requested address, usually the closest available station. The only exception is when two or more stations define a Catchment Area. In that case, one of them is selected automatically.

States of the ticket

After the ticket adapter has checked whether a ticket is needed and the answer is yes, the ticket is initialized immediately.

If this is true, for the VHH Hochbahn Adapter, the next step is that a connection with eos.uptrade is established and a ticket is requested. The Developer Test Adapter simply generates a test ticket.

This ticket is then offered to the passenger, which sets the state to offered.

If the passenger accepts the offer, and the driver accepts the ride, the state of the ticket is set to issued. That means the vendor has issued the ticket as an entitlement to the passenger. The ticket can now be downloaded or displayed in the browser.

Until now, the passenger has not yet seen the ticket. Only when they open the ticket is the state set to retrieved. Another way to set the status to retrieved is for a Super Admin to open the ticket in Control Center. This should be the exception and happen only for testing.

The ticket is canceled if the ride is canceled by the passenger or if it’s manually canceled by an administrator.

Fare and ticket prices

The ticketing adapter is part of matching and is called only after the matching algorithm has found a ride. At this point, eos.uptrade also communicates the ticket price.

Note in particular that this happens before the fare is calculated. Therefore, it is not possible, for example, to check for the best fare during matching.

The fare is calculated after the ticket is issued and is generally independent of the price communicated by eos.uptrade. However, the ticket price can be used to build the fare.

Cancellation

A ticket can be canceled either by the passenger or by an operator via Control Center, as long as it is in the state issued or retrieved. In this case, ioki Platform ticket is marked as canceled and a cancellation is also sent to eos.uptrade.

The only way for a passenger to cancel a ticket is by canceling the corresponding ride. Note that, at least for the VHH Hochbahn Adapter at present, this is possible only if the ticket is not yet valid.

For example, tickets issued for VHH Hochbahn are valid for a full calendar day. If a passenger wants to cancel a prebooked ride for which they needed a public transport ticket, the corresponding ticket can be canceled only if the booked ride is at least on the next day. If the passenger wants to cancel on the same day as the ride, it is still possible to cancel the ride, but it is no longer possible to cancel the ticket. The ticket can, however, still be downloaded and used as a public transport ticket. This means the cancellation fee is at least the amount of the ticket price.

An operator can also cancel a ticket via Control Center. For that admin procedure, see Ticketing in Control Center.

Personalization

Tickets are personalized. If a passenger books a ride for more than one person, the names on the ticket are indexed alphabetically. For example, if “Peter Passenger” wants to purchase a ticket for himself, Petra, and Patrick, the names on the tickets are:

• “Peter Passenger”,
• “Peter Passenger A” and
• “Peter Passenger B”.

Interface of a ticketing adapter

The interface of a ticket adapter always consists of four parts. These are given by:

1. Ticket needed?: Determines whether a ticket should be purchased along with a ride.
2. Build Offered Ticket: This is used to build the ticket which is then offered to the passenger.
3. Issue Ticket: Issues the ticket if it is booked.
4. Cancel Ticket: This is used to cancel a ticket.

VHH Hochbahn specifics

When booking a ride with an active VHH Hochbahn Adapter, a passenger can specify whether they already have a public transport ticket. If not, the ticket purchase is activated after matching. Otherwise, no additional ticket is needed.

A ticket bought via the VHH Hochbahn adapter is always valid for a calendar day. Once the ticket is valid, it can no longer be canceled.

Permissions: read_tickets, cancel_tickets