Move & Unlink Flow for Motics tickets in Google Wallet

This page describes implementing a move and unlink ticket flow for Motics tickets. To provide a good user experience, a user should be able to move their Motics ticket from one device to another, within certain limits defined by the issuer. The issuer has to restrict a ticket to one device. The user must delete the original ticket before saving it to a new device. If the user cannot delete the original ticket (perhaps because they lost the device), the issuer must unlink the ticket from the old device.

The Move & Unlink flow has to fulfil the following requirements:

  • A Motics ticket must only be usable on one device at a time.
  • The user must be able to move the Motics ticket to a new device in these cases:
    • Access to old device, for example when upgrading to a new device.
    • No access to old device, for example when a device is lost or stolen.
  • The number of moves or ticket activations should be limited by suitable controls on the Motics ticket issuer side, as defined by the PTO's business requirements.

User Experience

This section describes in more detail the two different scenarios for the User Experience, depending on whether the user still has access to their old device when attempting to move a Motics ticket.

User has access to old device

In such cases, the user can initiate the move flow from their old device:

  1. The user deletes the Motics ticket from the Wallet app on their old device.
  2. The user finds the confirmation email from the issuer on their new device or logs in to the ticketing webshop or portal and clicks a Save to Google Wallet link to resave the ticket to the Google Wallet app.

User does not have access to old device

When the user does not have access to their old device, they need to initiate the unlink and move flow from either the webshop ticketing portal, or by contacting the customer support of the issuer, that can initiate the unlink flow on the user's behalf.

  1. The user finds the confirmation email from the issuer with instructions to call customer service for assistance or starts an unlink flow from the issuer website or ticketing portal. This could be an unlink button on the ticketing portal.
  2. The issuer unlinks the ticket from the old device on behalf of the user (more details in the Issuer Responsibilities section).
  3. The ticket will be unusable (barcode won't scan) on the original device as soon as the issuer unlinks it.
  4. The issuer should denylist the old ticket, to ensure it can no longer be scanned by inspection devices.
  5. The ticket will automatically be deleted from the original device as soon as it comes online again (best-effort).
  6. The user finds the confirmation email from the issuer on their new device or logs in to the ticketing webshop or portal and clicks a Save to Google Wallet link to resave the ticket to the Google Wallet app.

Issuer Responsibilities

  • During initial setup the issuer must insert the transitClass with multipleDevicesAndHoldersAllowedStatus=ONE_USER_ONE_DEVICE.
  • The confirmation email that the issuer sends to the user at purchase time has to contain instructions for how to move the ticket to a new device.
  • The confirmation email has to contain an identifier for the ticket to the help in the support process.
  • To keep contact volume to a minimum, the issuer should also have an unlink button on their webshop or ticket portal where a user can manage their ticket.
  • The issuer is responsible for limiting the number of times a ticket can be activated. This is to avoid users moving the same ticket back and forth between devices (both logged into the same account on Wallet) indefinitely.
    • The issuer has to keep track of how many times the activation endpoint is called for the same objectId, and reject the activation request if it exceeds the limit.
    • Since each issuer has its own rules on how many times a ticket can be moved, Google requires that issuers handle limiting ticket moves on their end.
  • If the user wants to unlink the ticket through contacting customer support:
    • If the user cannot remove the ticket from the old device, the issuer unlinks the ticket by calling transitObject:patch with {hasLinkedDevice:false} for the objectId of the ticket.
      • The issuer will need to find the objectId for the given ticket. They should look this up based on the identifier given to the user in the confirmation email.
  • If the user initiates the unlink flow on the webshop or ticket portal:
    • The issuer unlinks the ticket by calling transitObject:patch with {hasLinkedDevice:false} for the objectId of the ticket.
  • The issuer should denylist the old ticket, so that it can no longer be scanned by inspection devices.

Google Responsibilities

In response to receiving the transitObject:patch with {hasLinkedDevice:false} call, Google will revoke the existing certificate (if there is one) with the Motics server. If the user does still have their old device with the original ticket, the barcode will no longer work as it will be deleted from the old device as long as it is online or comes online again.

Sequence Diagram

Figure 1. Motics Ticket Unlink Flow Motics Ticket Unlink Flow

Figure 1 shows the transitObject:patch and pruneTree() calls that take place to unlink a ticket when the user no longer has access to their old device.