Use cases

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

If there are changes to a transit pass after it's saved, you can use the update or patch REST API to deliver those changes to passengers.

To update the way passes are displayed, you only need to update or patch the TransitClass. A change to a TransitClass 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 update or 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 TransitObject list method.

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 update or patch REST API calls for each and every TransitObject.

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 TransitObject.

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.

Multi-leg 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:

  1. object.tripId
  2. object.purchaseDetails.confirmationCode

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 a particular 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.ticketLegs[].arrivalDateTime or
  • If object.state is marked as expired, inactive, or completed.

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.

Once a user has a pass saved, reference its objectId in order to link to the pass.

Use the following link to reference the pass:{<issuerId>}.{<ObjectId>}

The pass can be viewed with the Google Pay app or a web browser.

Send feedback about...

Google Pay for Passes