This guide outlines specific ways that you can use the Google Pay API for Passes to engage with your customers for the transit pass vertical. The API allows you to offer your customers the following options:
- Update transit passes.
- Define journeys with multiple legs.
- Make a button to save multiple passes.
- Group multiple transit passes.
- Handle expired passes.
- Receive upcoming notifications.
Update transit passes
If there are changes to a transit pass after it's saved, you can use the
patch REST API to deliver those changes to passengers.
To update the way passes are displayed, you only need to
TransitClass. A change to a
propagates to all objects associated with that class. This is a fast and easy way to update
the look and feel of many passes with a few calls.
To update a single pass, such as when the estimated departure time changes, you need to
patch a single
TransitObject. This is the
case for all fields defined at the
TransitObject level, even if the value of
the field is shared among a subset of
TransitObject objects. You can find
all objects of a particular class if you call the
Sometimes, you might not know when a change happens, or when to trigger an update or
patch REST API call. In that case, periodically schedule
patch REST API calls for each and every
Define journeys with multiple legs
Often, one journey includes multiple legs rather than a direct trip to a person's destination.
In order to fulfill this journey, transit operators may issue one pass for each leg of the
journey or a single pass. The Google Pay API for Passes mimics this behavior, with either one
TransitObject per leg or a single multi-leg
It's very simple to use one
TransitObject per leg. You can use
object.ticketLeg to define the leg. You can create and update each pass as if
they were independent. However, you might want to define a way to group these passes together.
For more details, see Group multiple transit passes.
This is the preferred way to define journeys with multiple legs.
TransitObject objects should be used only if this type of aggregated
pass is accepted in each leg and only if the information on the pass, for example the QR code,
is the same for all the legs. You can use the
object.ticketLegs list to define
the legs. The card portion of the pass only shows the first leg origin and the last leg
destination, while a full itinerary is displayed in the details section of the pass.
Make a button to save multiple passes
If a user buys multiple passes and is likely to save all of them to Google Pay, then it's useful to allow a user to save many objects with one click of a Save to Google Pay button or link. Multiple objects or classes can be defined in the JSON Web Token (JWT).
The JWT must be made in either of the following formats:
- Only pre-inserted classes and objects are used.
- Only object and class resources that are fully defined within the JWT are used.
For more information on the UI representation of Passes, see Group multiple transit passes.
Group multiple transit passes
There are features which work differently if they're used on a group rather than individual objects, such as status notifications or the organization of multiple Passes saved for many passengers on the user interface.
TransitObject objects are only considered to be a group if they share the same
object.classId, object.ticketLeg.departureDateTime, and one of the following
properties listed by priority:
This is meant to group passes for the same journey but for different passengers.
If you wish for passes to be grouped, we recommend you consistently set these fields, even if
TransitObject isn't grouped with any other.
Handle expired passes
There's an "Expired passes" section that contains all archived or inactive passes under the "Passes" tab of the Google Pay app. A transit pass is moved to the "Expired passes" section if at least one of the following conditions is true:
- If 24 hours have passed since
object.ticketLeg.arrivalDateTime, or the last
object.stateis marked as
Receive upcoming notifications
Google Pay sends a notification to the user three hours prior to their departure time. The notification has an unmodifiable format.
To receive this status notification about their next departure, a user must navigate to Settings > Notifications and turn on Updates about your passes.
If the user has multiple passes grouped together, only one notification is shown. A status notification doesn't auto-dismiss after a user opens it. Auto-dismiss occurs 60 minutes after the scheduled departure time.