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 boarding passes for flights. The concepts discussed in this guide should help you better understand the capabilities of saved boarding passes for flights.

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

FlightClasses and FlightObjects

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

FlightClass

The FlightClass holds data that all passengers or a subset of passengers have in common for a specific flight at a specific date and time. For example, common data may be the carrier, origin, destination, flight number, or departure time. All passengers on the flight would have the same data on their boarding passes.

A FlightClass can also hold common data for a subset of passengers on the same plane. For example, you could create three different FlightClass structures for first class, business class, and economy class. This would allow you to use different fields for each subset, if necessary. In this case, all three classes would still represent the same plane, flying the same route, at a specific date and time.

FlightObject

A FlightObject represents each passenger who flies on a specific plane at a specific point in time. For example, the FlightObject contains the passenger name, seat number, and boarding barcode. These are different on each passenger's boarding pass.

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

Supported countries

To learn which countries support boarding passes for flights, see the supported country list. We suggest that you limit where you display the Save to Google Pay button based on where the user has purchased the ticket from.

Use cases

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

• Update passes.
• Save a flight journey with multiple legs.
• Make a button to save multiple passes.
• Group multiple boarding passes.
• Receive upcoming flight notifications.
• Receive flight update 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 fields for all of the boarding passes for a specific flight, such as when the estimated departure time changes, you only need to update or patch the FlightClass or use the Google Pay Merchant Center. Google propagates this information to all FlightObjects associated to the updated FlightClass. This is the case for all fields defined at the FlightClass level.

To update a single pass, such as when the seat number for one passenger changes, you need to update or patch a single FlightObject. This is the case for all fields defined at the FlightObject level.

Note: See FlightClass and FlightObject 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 FlightClass list method. You can find all objects of a particular class if you call the FlightObject list method.

Data sources for flight updates

If the time given by class.localScheduledDepartureDateTime was in the past 24 hours or is in the next 48 hours, a flight status card appears to users. When this happens, Google Pay can display data from either Google Flights or the information given in the Google Pay pass. Which source is used depends on the following:

• If class.localEstimatedOrActualDepartureDateTime is not provided, then Google Flights is used. In this case, any class.flightStatus you set is ignored.

  For instance, if a flight is delayed, users see a card under the "Home" tab of the Google Pay app that displays the new departure time. A similar delay card also surfaces to users under the "Passes" tab.

• If you've provided the class.localEstimatedOrActualDepartureDateTime but not class.flightStatus, the provided time is used to determine if a flight is delayed. The flight status on the card is then surfaced to users based on the following logic:
  • If class.localEstimatedOrActualDepartureDateTime is greater than class.localScheduledDepartureDateTime, show users a card with the flight listed as delayed.
  • If class.localEstimatedOrActualDepartureDateTime is not greater than class.localScheduledDepartureDateTime, show users the card with the flight information but without any status message.

If you don't want to use Google Flights as a source of information about flights, be sure to provide the flightStatus, localScheduledDepartureDateTime, and localEstimatedOrActualDepartureDateTime of a FlightClass. Only your data is used on the card. Alternatively, if you use an ICAO carrier code instead of an IATA code in FlightClass, Google Flights is not used as a source of flight information.

When certain fields are changed, the user receives push notifications about the changes. For more details, see Receive flight update notifications.

Save a flight journey with multiple legs

Often, one flight journey includes multiple legs rather than a direct journey to a person's destination. During this journey, airlines issue one boarding pass per leg of the journey. The Google Pay API for Passes mimics this behavior, with one FlightObject per leg.

This means if you have two passengers who fly from SFO to LAX to TPE, there would be two FlightClass structures and four FlightObject objects:

	FlightClass A (SFO to LAX: Carrier, flight number, departure time)	FlightClass B (LAX to TPE: Carrier, flight number, departure time)
Passenger Q	FlightObject: id_01	FlightObject: id_02
Passenger Z	FlightObject: id_03	FlightObject: id_04

These fields reflect the physical boarding passes. Both Passenger Q and Passenger Z would have two paper boarding passes.

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 an example of how to create a button for multiple passes, see Save multiple passengers button.

For more information on the UI representation of Passes, see Group multiple boarding passes.

Group multiple boarding 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.

FlightObject objects are only considered to be a group if all of the following properties are the same for each object:

• Issuer ID (from Google Pay API for Passes Merchant Center)
• class.flightHeader.carrier.carrierIataCode
• class.flightHeader.flightNumber
• class.localScheduledDepartureDateTime
• object.reservationInfo.confirmationCode

If two FlightObject objects differ on any of the above properties, they are not considered to be grouped.

Note: Some of these are class properties, and some are object properties. This enables FlightObject objects of different classes to be grouped.

Receive upcoming flight notifications

Google Pay sends a notification to the user three hours prior to the flight. The flight time is defined by class.localScheduledDepartureDateTime.

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:

Boarding pass for your flight to class.destination.airportIataCode
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 boarding 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 class.localScheduledDepartureDateTime.

Receive flight update notifications

When certain fields of a flight are changed, users with one or more boarding passes saved receive a push notification on their devices. This happens only if certain conditions are met.

Origin terminal and gate

If you change class.origin.terminal or class.origin.gate, and the following condition is met, a notification is sent that the field has changed.

• There are less than three hours to go before class.localScheduledDepartureDateTime.

The notification is in the following format: “Sample Airlines has updated your gate to A1.” The format cannot be changed.

Boarding time and departure time

If you change class.localBoardingDateTime or class.localEstimatedOrActualDepartureDateTime, and conditions below are met, a notification is sent that the field has changed.

• There are less than 24 hours to go before class.localScheduledDepartureDateTime.
• The respective time changes by at least 10 minutes or more.

The notification is in the following format: "Sample Airlines has updated your boarding time to 6:00PM." The format cannot be changed.

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 class.localScheduledDepartureDateTime or class.localEstimatedOrActualDepartureDateTime expired. The pass moves to "Expired passes" anytime between 24-48 hours after class.localScheduledDepartureDateTime or class.localEstimatedOrActualDepartureDateTime 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
              }
            }
    }
  }
  …
  …
  …
}