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 Gift card vertical.

Update monetary balance

Updating the gift card balance is an important way to engage with your customer.

Any update should begin with a GET request to retrieve the GiftCardObject. This ensures the latest version of the object is used. The version of the object should be incremented when the balance is changed. To save the updated object, make a PUT request.

The following REST URIs are used to GET an object and to UPDATE an object:


The following code samples provide examples of how to update an object in different languages. Take note of the balance property:


  "kind" : "walletobjects#giftCardObject",
  "classId" : "1234567890.ExampleGCClass",
  "id" : "1234567890.ExampleGCObject",
  "cardNumber" : "123jkl4889",
  "pin" : "1111",
  "eventNumber" : "123456",
  "balance" : {
    "kind" : "walletobjects#money",
    "micros" : 20000000,
    "currencyCode" : "USD"
  "balanceUpdateTime" : {
    "date" : '2014-01-12T23:20:50.52Z'
  "barcode" : {
    "alternateText" : "12345",
    "type" : "qrCode",
    "value" : "28343E3"
  "textModulesData" : [{
    "header" : "Earn double points",
    "body" : "Jane, don't forget to use your Baconrista Rewards when " +
              "paying with this gift card to earn additional points"
  "linksModuleData" : {
    "uris" : [
        "kind" : "walletobjects#uri",
        "uri" : "",
        "description" : "My Baconrista Gift Card Purchases"
  "state" : "active"


Barcode barcode = new Barcode().setType("qrCode")

Money balance = new Money();

DateTime balanceUpdateTime = new DateTime();
balanceUpdateTime.setDate(new Date()));

// Define Text Module Data
List<TextModuleData> textModulesData = new ArrayList<TextModuleData>();
TextModuleData textModuleData = new TextModuleData()
    .setHeader("Earn double points")
    .setBody("Jane, don't forget to use your Baconrista Rewards when " +
                "paying with this gift card to earn additional points");

// Define Links Module Data
List<Uri> uris = new ArrayList<Uri>();
Uri uri1 = new Uri().setDescription("My Baconrista Gift Card Purchases")
LinksModuleData linksModuleData = new LinksModuleData().setUris(uris);

// Define Wallet Instance
GiftCardObject object = new GiftCardObject()


// Define barcode type and value.
$barcode = new Google_Service_Walletobjects_Barcode();
// Define text module data.
$textModulesData = array(
        'header' => 'Earn double points',
        'body' => 'Jane, don\'t forget to use your Baconrista Rewards when '.
                  'paying with this gift card to earn additional points'
// Define links module data.
$linksModuleData = new Google_Service_Walletobjects_LinksModuleData();
$uris = array (
        'uri' => '',
        'kind' => 'walletobjecs#uri',
        'description' => 'My Baconrista Gift Card Purchases'

$balance = new Google_Service_Walletobjects_Money();

$balanceUpdateTime = new Google_Service_Walletobjects_DateTime();

// Create wallet object.
$giftCardObject = new Google_Service_Walletobjects_GiftCardObject();


giftcard_object = {
    'kind' : 'walletobjects#giftCardObject',
    'classId' : '1234567890.ExampleGCClass',
    'id' : '1234567890.ExampleGCObject',
    'cardNumber' : '123jkl4889',
    'pin' : '1111',
    'eventNumber' : '123456',
    'balance' : {
      'kind' : 'walletobjects#money',
      'micros' : 20000000,
      'currencyCode' : 'USD'
    'balanceUpdateTime' : {
      'date' : datetime.datetime.utcnow().isoformat("T") + "Z"
    'barcode' : {
        'alternateText' : '12345',
        'type' : 'qrCode',
        'value' : '28343E3'
    'textModulesData': [{
      'header': 'Earn double points',
      'body': 'Jane, don\'t forget to use your Baconrista Rewards when  ' +
              'paying with this gift card to earn additional points. '
    'linksModuleData': {
      'uris': [
          'kind': 'walletobjects#uri',
          'uri': '',
          'description': 'My Baconrista Gift Card Purchases'
    'state': 'active'

Save in the Google Pay app

Users can add a gift card to their Google Pay app by either scanning or manually adding the gift card details. The Google Pay API for Passes creates a GiftCardObject that doesn't reference a GiftCardClass you've previously defined. No action is required on your part to create the new object or class.

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:


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


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



$locations = array(
    '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


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 gift card is moved to the "Expired passes" section if at least one of the following conditions is true:

  • The of the gift card has passed. The pass may move to "Expired passes" anytime up to 24 hours after
  • The state field of GiftCardObject 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:{<issuerId>}.{<ObjectId>}

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

Send feedback about...

Google Pay for Passes