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 COVID cards

---

The Google Pay API for Passes allows you to engage with users through loyalty cards. The concepts discussed in this guide should help you better understand the capabilities of saved loyalty cards.

The following use cases are available only for the Loyalty vertical:

• Update passes.
• Scan in the Google Pay app.
• Linked offers.
• Geofenced notifications.
• Handle expired passes.
• Link to a saved pass.
• Link out from a saved pass.
• Enrollment and sign-in.

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 manage them in the Business Console. 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 LoyaltyClass or use the Business Console. Google propagates this information to every LoyaltyObject associated to the updated LoyaltyClass. This is the case for all fields defined at the LoyaltyClass level.

To update a single pass, such as when the loyalty card points balance changes, you need to update or patch a single LoyaltyObject. This is the case for all fields defined at the LoyaltyObject level.

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 LoyaltyClass list method. You can find all objects of a particular class if you call the LoyaltyObject list method.

Scan in the Google Pay app

Users can add some loyalty card to their Google Pay app when they either scan or manually add the loyalty card details. The Google Pay API for Passes creates a LoyaltyObject that doesn't reference a LoyaltyClass you've previously defined. No action is required on your part to create the new object or class. However, the LoyaltyObject created by the Google Pay API for Passes can't be updated and behaves like a static pass.

Linked offers

Important: Linked offers are temporarily unavailable for most users while we make platform improvements. We'll update this feature in an upcoming release.

Linked offers allow existing offers to appear within the loyalty card view, making relevant content easier for the user to discover. The writable list field linkedOfferIds in a LoyaltyObject indicates which offers are associated with the loyalty card.

Creating the offer before linking

To link a linked offer, the offer classes and objects linked to the loyalty card must already be created. To learn more about creating offers, see Offers. Unlike standalone offers, linked offers do not require a user to explicitly save the offer. The id field found in the OfferObject is used to point to the LoyaltyObject.

Link offers to a loyalty card

The existing offers can be linked to a loyalty card using the REST API calls insert, or update, or patch, or modifyLinkedOfferObjects.

When offers are linked to a loyalty card upon creation of the loyalty card using the insert call or when offers are both linked and unlinked to an existing loyalty card using the update call, the field linkedOfferIds can be written with the rest of the LoyaltyObject using the established format:

{
  "id": "2945482443380251551.ExampleObject1",
  "classId": "2945482443380251551.ExampleClass1",
  ...
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

Note: If you update an existing LoyaltyObject without the writable field linkedOfferIds, all offers are unlinked.

When offers are linked and unlinked to an existing loyalty card using the patch call, the field linkedOfferIds can be the only field in the request:

{
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

Note: To unlink all linked offers with a patch call you must explicitly set the linkedOfferIds field to null or [].

However, in order to avoid mistakes when dealing with arrays, specify which linked offers need to be added and which need to be removed, and be able to omit the linked offers that should remain untouched. We recommend to use the modifyLinkedOfferObjects method as in the following example:

{
  "linkedOfferObjectIds" {
    "addLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject1",
      "2945482443380251551.OfferObject2"
    ],
    "removeLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject3",
      "2945482443380251551.OfferObject4"
    ]
  }
}

Designing loyalty card with linked offers

Linked offers will appear in a loyalty card view between the card section and the details section, as shown below. Only a maximum of 5 linked offers are displayed in the carousel. If more offers are linked to the loyalty card, the user can click on the "More" button at the end of the carousel to display them all.

RECOMMENDED OFFERS offerObject.heroImage or offerClass.heroImage or mainObject.hexBackgroundColor or mainClass.hexBackgroundColor offerClass.localizedTitle or offerClass.title EXPIRES: offerObject.validTimeInterval.end

Note: If the hero image is missing in the linked OfferClass, the linked offer uses the background color of the LoyaltyClass in this view.

When clicked the linked offer uses a simplified offer design, as shown below.

offerObject.heroImage or offerClass.heroImage offerObject.barcode.type and offerObject.barcode.value offerObject.barcode.alternateText offerClass.localizedTitle or offerClass.title offerClass.details EXPIRES: offerObject.validTimeInterval.end offerClass.finePrint

Note: The simplified offer design always uses a white background.

Note: This image includes all fields necessary to complete the simplified offer design. However, not all of these fields are required to create a valid OfferClass or OfferObject. Refer to the OfferClass insert and the OfferObject insert methods for a list of required fields.

Geofenced notifications

Google can trigger notifications related to a consumer's saved Object based on the consumer's proximity to a location you've defined.

There are two ways geolocation information is added:

1. Geolocation information from Google Maps is used when a Google Pay API for Passes issuer account is created.
2. Coordinates can be added to the object or class through the REST API.

For instructions on adding coordinates to objects or classes, see Add geolocation information using the REST API.

Important: Geofenced notifications are temporarily unavailable for a majority of users while we make platform improvements. We'll completely update this feature in an upcoming release.

Geofencing concepts

Google uses geolocation information in Google Maps to algorithmically determine whether the user is physically in the store or area. This detection applies to all classes and objects developed under the Google Pay API for Passes issuer account.

The algorithm considers GPS, Wifi, Bluetooth, movement, dwell time, and other factors. When the user is determined to be physically present, a geofenced notification is triggered.

If coordinates are manually specified in the Object, the geofenced notification is triggered when they are 150 meters from the coordinates.

Frequency, throttling, and user opt-out of geofenced notifications

At maximum, a user receives up to four notifications per day.

When there are multiple saved objects within the geofence, a single (per Google Pay API for Passes issuer account), unmodifiable notification with a carousel appears. Objects are cyclable within the carousel:

For geofenced notifications to work, the user must enable Updates about your items in the Google Pay app’s notification settings and must have location services turned on for their device.

Add geolocation information using the REST API

You can specify an array of locations (latitudes and longitudes) in your classes or objects. Google checks the user's current geolocation against the list of locations associated with a class or object and notifies the user if they are within 150 meters of one of the locations. The following are code samples showing how to specify locations in your classes or objects:

Resource

{
  ... //Class or Object content

  "locations": [{
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.422087,
    "longitude": -161446
  }, {
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.429379,
    "longitude": -121.12272999999999
  }, {
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.333646,
    "longitude": -122.884853
  }]
}

Java

List<LatLongPoint> locations = new ArrayList<LatLongPoint>();
locations.add(new LatLongPoint().setLatitude(37.422087).setLongitude(
    -122.161446));
locations.add(new LatLongPoint().setLatitude(37.429379).setLongitude(
    -121.12272999999999));
locations.add(new LatLongPoint().setLatitude(37.333646).setLongitude(
    -122.884853));

yourClassOrObject.setLocations(locations);

PHP

$locations = array(
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.442087,
    'longitude' => -122.161446
  ),
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.429379,
    'longitude' => -122.12272999999999
  ),
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.333646,
    'longitude' => -121.884853
  )
);

Python

offer_class_object = {
  # class or object content
  'locations': [{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.442087,
    'longitude': -122.161446
    },{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.429379,
    'longitude': -122.12272999999999
    },{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.333646,
    'longitude': -121.884853
  }]
}

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:

• 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 Contact Support button in Business Console. Select Passes as the topic first, and then select App linking as the support type.

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
              }
            }
    }
  }
  …
  …
  …
}

Enrollment and sign-in

The loyalty enrollment and sign-in feature lets users to search for your loyalty program and join or sign-in to their account from Google Pay. For more details, read Enrollment and sign-in.