Use cases

Select one of the following pass verticals to learn more about how it can be used.

Boarding passes Event tickets Gift cards Loyalty Offers Transit passes

---

The Google Pay API for Passes allows you to engage with users through transit passes for buses, ferries, trains, and more. The concepts discussed in this guide should help you better understand the capabilities of transit passes.

Note: This documentation contains integration support for barcode/QR transit only. For other types of transit integrations, see the Transit passes support page.

For boarding passes for flights, see the boarding passes vertical.

To implement transit passes, use the JWT POST request method or "skinny" JWT links, which are methods that pre-insert the classes and objects.

TransitClasses and TransitObjects

Like other verticals in Google Pay API for Passes, data for transit passes is stored in two data structures: TransitClass and TransitObject. This guide explains how these data structures can be used to support your transit passes.

TransitClass

TransitClass defines the template that's used to display any object that is associated with the class. The template defines which fields to display in different sections of the pass. It also defines the logo and the issuer name that are shared among objects.

If two pass types require different data to be displayed in one or more sections of the pass, you might wish to create two separate TransitClasses. For example, one TransitClass to use for any point-to-point single-use passes and another TransitClass to use for seasonal passes.

TransitObject

A TransitObject holds all the data that represents the journey, the transit carrier, and the passenger(s). For example, the TransitObject contains the journey origin, journey destination, time of departure, transit carrier number, passenger name, seat number, and more. Some of these values are shared among multiple TransitObjects.

The resources contained in a TransitObject are saved to a user's Google Pay app.

Supported countries

To learn which countries support the Google Pay app, see the supported country list. We suggest that you limit where you display the Save to Google Pay button based on where the user purchases the ticket from.

Use cases

The following use cases are available only for the Transit Pass vertical:

• Update passes.
• Define journeys with multiple legs.
• Make a button to save multiple passes.
• Group multiple transit passes.
• Receive upcoming journey notifications.
• Handle expired passes.
• Link to a saved pass.
• Link out from a saved pass.

Note: All Pass verticals share core functionalities. For more information, see Save passes to Google Pay, Redeem passes from Google Pay, and Engage users through Google Pay.

Update passes

If there are changes to a pass after it's created, use the REST API to deliver those changes to users. If the changes affect only classes, you can also use the Google Pay Merchant Center. Pass updates are an important way to engage with your users.

To update the way passes are displayed, such as when the logo changes, you only need to update or patch the TransitClass or use the Google Pay Merchant Center. Google propagates this information to all TransitObjects associated to the updated TransitClass. This is the case for all fields defined at the TransitClass level.

To update a single pass, such as when the departure time changes, you need to update or patch a single TransitObject. This is the case for all fields defined at the TransitObject level.

Note: See TransitClass and TransitObject for more information on these data structures.

Note: To understand more about the difference between update and patch, see Patch (partial update).

Any update logic should begin with a GET request to retrieve the class or object. This ensures that the latest version of the class or object is used. Fields that you omit are cleared.

In general, it's much safer to use patch when you only supply data for the fields that you want to change. Fields that you omit aren't cleared. However, you should take extra care when you modify arrays. Patch requests that contain arrays also replace the existing array with the one you provide. You cannot modify, add, or delete items in an array in a piecemeal fashion.

Sometimes, you might not know when a change happens, or when to trigger an update or patch request. In cases like that, periodically schedule update or patch requests for each and every class and object. You can find all classes of a particular issuer account if you call the TransitClass list method. You can find all objects of a particular class if you call the TransitObject list method.

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 they're 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. You can define multiple objects or classes when you sign the JSON Web Token (JWT).

You must create the JWT in either of the following formats:

• With pre-inserted classes and objects only.
• With only object and class resources that are fully defined within the JWT.

Note: The format of the JWT must be consistent, so that only one format or the other is 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 saved Passes in 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.

Receive upcoming journey notifications

Google Pay sends a notification to the user one hour prior to the journey. The journey time is defined by object.ticketLeg.departureDateTime or the first object.ticketLegs[].departureDateTime.

To receive this notification, the user must have notifications enabled. To check this, they can navigate to Settings > Notifications and see if Updates about your passes is turned on.

The notification shows up in the notifications area, and in the lock screen, if the user has notifications enabled for the lock screen.

The notification has the following unmodifiable format:

Ticket fot your upcoming trip to object.ticketLeg.destinationName
Expand for more options

If they tap the notification and unlock their device, their pass appears in the Google Pay app.

If the user has multiple passes, only the soonest useable pass is shown. If they've saved grouped passes as per Group multiple transit passes, the notification only shows one of the passes in the group. However, when they tap it, the user can swipe left and right to see the other passes in that group.

The notification is pinned and won't auto-dismiss after a user opens it. Auto-dismiss occurs 60 minutes after object.ticketLeg.departureDateTime or the first object.ticketLegs[].departureDateTime.

Handle expired passes

Under the "Passes" tab of the Google Pay app, there's an "Expired passes" section that contains all archived or inactive passes. A pass is moved to the "Expired passes" section if at least one of the following conditions is true:

• It's been at least 24 hours since object.ticketLeg.arrivalDateTime or the last object.ticketLegs[].arrivalDateTime expired. The pass moves to "Expired passes" anytime between 24-48 hours after object.ticketLeg.arrivalDateTime or the last object.ticketLegs[].arrivalDateTime expires.
• object.validTimeInterval.end.date expires. The pass moves to "Expired passes" anytime up to 24 hours after object.validTimeInterval.end.date expired.
• The object.state field is marked as Expired, Inactive, or Completed.

Link to a saved pass

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:

https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}

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

Note: If the user doesn't have the pass saved, they receive an "Item not found" error. If the user has the Google Pay app installed, the link works offline.

Link out from a saved Google Pay pass

You can link to your app or website below the header of a saved Google Pay pass. This feature is available for all types of Google Pay passes.

Note: This feature is only available if you've completed two or more integrations with Google Pay for Passes API. These must be app, web, or email integrations.

Request access

Request access with the support form for in-store merchants. Keep the following in mind:

• You must share your issuer ID in the form.
• Under Issue type, select "Technical/API Integration."
• Select Link your app or website below the Google Pay pass.

Set the app link on your Google Pay pass

For a given Google Pay pass, define appLinkData to set the URI of your app or website. The URI can be any format, but we recommend that you use a dynamic link.

The format and context of the appLinkData field can be seen in the following source code:

{
  "id": string,
  "classId": string,
  …
  …
  …
  "appLinkData": {
    "androidAppLinkInfo": {
      "appLogoImage": {
        "sourceUri": {
          "uri": string
        }
      },
        "title": {
          "defaultValue": {
            "language": string,
              "value": string
          }
        },
          "description": {
            "defaultValue": {
              "language": string,
                "value": string
            }
          },
            "appTarget": {
              "targetUri": {
                "uri": string,
                  "description": string
              }
            }
    }
  }
  …
  …
  …
}