Use cases

This guide outlines the following specific ways that you can use the Google Pay API for Passes to engage with your customers for the Offers vertical.

Offer expiration notification

To remind users to use offers before they expire, a default notification is triggered 48 hours before an offer expires. To trigger a notification, an offer must meet the following criteria:

  1. It must not have previously triggered an expiration notification on the user’s device.
  2. It must have a valid expiration datetime that's in the future, set in validTimeInterval.end.date.
  3. It must have been saved on the user's device for over 12 hours.
  4. It must not have the writeable field disableExpirationNotification set to True. By default, this field is set to false.

The following screenshot shows an example of the default, unmodifiable notification:

  1. Offer expires (today, tomorrow, in [x] days)
  2. class.title
  3. class.titleImage

The header in the offer expiration notification cannot be customized.

Blackout hours

If the offer expiration notification is set to appear between 10PM and 6AM at the user’s local time, the offer appears either before or after this time period.

Custom offer expiration notification time

You can customize when the Offer expiration notification appears using the message.displayInterval.start.date field on OfferObjects or OfferClasses. If a custom notification time is set, the expiration notification triggers according to the message.displayInterval.start.date, instead of the default logic calculated from validTimeInterval.end.date. The following is a sample of a customized time for an expiration notification:

{
  “message”: {
   “messageType”: “expirationNotification”,
   “displayInterval”: {
     “start”: {
      “date”: datetime
     }
   }
  }
}

The displayInterval.start.date sets the time the notification appears. It can be set up to 30 days prior to the expiration date. If a time span greater than this is specified, the notification triggers at the 30 day mark. This message doesn't require a header and body field - if they're included they aren't used.

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 Merchant Center 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.

Geofencing concepts

Using geolocation information in Google Maps, Google algorithmically determines if 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 Merchant Center 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 Merchant Center 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 offer is moved to the "Expired passes" section if at least one of the following conditions is true:

  • The object.validTimeInterval.end.date of the offer has passed. The pass may move to "Expired passes" anytime up to 24 hours after object.validTimeInterval.end.date.
  • The state field of OfferObject is marked as Expired, Inactive, or Completed.

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.

Send feedback about...

Google Pay for Passes